001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.juneau.bean.mcp.v20260728;
018
019/**
020 * Shared SEP-2549 cache-hint base for the five cacheable {@code 2026-07-28} result carriers
021 * ({@code tools/list}, {@code prompts/list}, {@code resources/list}, {@code resources/templates/list}, and
022 * {@code resources/read}).
023 *
024 * <p>
025 * Extends {@link Result} so every cacheable result also inherits the required {@code resultType} discriminator
026 * and optional {@code _meta}, alongside two nullable, independent, top-level cache-hint properties that are
027 * peers of each subclass's own payload properties:
028 * <ul>
029 *    <li>{@code ttlMs} - Freshness duration in milliseconds ({@code Cache-Control: max-age} semantics).
030 *       {@code 0} means immediately stale.
031 *    <li>{@code cacheScope} - {@link McpCacheScope#PUBLIC} or {@link McpCacheScope#PRIVATE}. An absent value is
032 *       interpreted by consumers as {@code public}, but that interpretation is never materialized on the wire.
033 * </ul>
034 *
035 * <p>
036 * This base is a lossless wire carrier only: it performs no {@code ttlMs} validation and does not synthesize a
037 * default {@code cacheScope}. Wire beans must be able to parse and round-trip arbitrary protocol payloads
038 * (including a negative parsed {@code ttlMs}) independently of any server-side configuration policy. TTL
039 * validation for values the server itself emits is owned by the {@code 2026-07-28} adapter's cache
040 * configuration, not by this bean.
041 *
042 * <p>
043 * The CRTP type parameter lets each concrete subclass's cache setters (and the inherited {@link Result}
044 * setters) return its own concrete type for fluent chaining, without duplicating those accessors in every
045 * subclass.
046 *
047 * @param <T> The concrete subclass, for fluent-setter self-typing.
048 */
049@SuppressWarnings({
050   "unchecked" // CRTP subclasses bind T to their own concrete type.
051})
052public abstract class CacheableResult<T extends CacheableResult<T>> extends Result<T> {
053
054   private Integer ttlMs;
055   private McpCacheScope cacheScope;
056
057   /**
058    * Cache freshness duration in milliseconds.
059    *
060    * @return The TTL, or {@code null} if not set.
061    */
062   public Integer getTtlMs() {
063      return ttlMs;
064   }
065
066   /**
067    * Sets the cache freshness duration in milliseconds.
068    *
069    * @param value The new value. Can be <jk>null</jk> to unset the property. {@code 0} is a valid, meaningful
070    *    value meaning immediately stale.
071    * @return This object (for method chaining).
072    */
073   public T setTtlMs(Integer value) {
074      ttlMs = value;
075      return (T)this;
076   }
077
078   /**
079    * Cache-hint authorization scope.
080    *
081    * @return The scope, or {@code null} if not set.
082    */
083   public McpCacheScope getCacheScope() {
084      return cacheScope;
085   }
086
087   /**
088    * Sets the cache-hint authorization scope.
089    *
090    * @param value The new value. Can be <jk>null</jk> to unset the property.
091    * @return This object (for method chaining).
092    */
093   public T setCacheScope(McpCacheScope value) {
094      cacheScope = value;
095      return (T)this;
096   }
097}