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.rest.server.mcp;
018
019/**
020 * Revision-neutral identification of the declaration a {@code completion/complete} request targets.
021 *
022 * <p>
023 * Supersedes the wire-level closed {@code CompletionReference} family ({@code PromptReference} /
024 * {@code ResourceTemplateReference}). {@link #getTarget()} is always an <em>exact declaration</em>: a
025 * prompt name or a registered {@code uriTemplate} string, never a concrete/expanded URI.
026 *
027 * <p>
028 * Use {@link #prompt(String)} or {@link #resource(String)} to construct an instance; this keeps neutral
029 * dispatch code free of free-form kind strings.
030 */
031public class McpCompletionRef {
032
033   /**
034    * The kind of declaration a {@link McpCompletionRef} targets.
035    */
036   public enum Kind {
037
038      /** Targets a declared prompt argument. */
039      PROMPT,
040
041      /** Targets a declared resource-template variable. */
042      RESOURCE
043   }
044
045   private Kind kind;
046   private String target;
047
048   /**
049    * Creates a reference to a prompt argument completion target.
050    *
051    * @param name The exact prompt name. Can be <jk>null</jk>.
052    * @return A new reference. Never <jk>null</jk>.
053    */
054   public static McpCompletionRef prompt(String name) {
055      return new McpCompletionRef().setKind(Kind.PROMPT).setTarget(name);
056   }
057
058   /**
059    * Creates a reference to a resource-template variable completion target.
060    *
061    * @param uriTemplate The exact registered URI template string. Can be <jk>null</jk>.
062    * @return A new reference. Never <jk>null</jk>.
063    */
064   public static McpCompletionRef resource(String uriTemplate) {
065      return new McpCompletionRef().setKind(Kind.RESOURCE).setTarget(uriTemplate);
066   }
067
068   /**
069    * The kind of declaration this reference targets.
070    *
071    * @return The kind, or <jk>null</jk> if not set.
072    */
073   public Kind getKind() {
074      return kind;
075   }
076
077   /**
078    * Sets the kind of declaration this reference targets.
079    *
080    * @param value The new value. Can be <jk>null</jk> to unset the property.
081    * @return This object.
082    */
083   public McpCompletionRef setKind(Kind value) {
084      kind = value;
085      return this;
086   }
087
088   /**
089    * The exact target declaration: a prompt name for {@link Kind#PROMPT}, or a registered URI template
090    * string for {@link Kind#RESOURCE}.
091    *
092    * @return The target, or <jk>null</jk> if not set.
093    */
094   public String getTarget() {
095      return target;
096   }
097
098   /**
099    * Sets the exact target declaration.
100    *
101    * @param value The new value. Can be <jk>null</jk> to unset the property.
102    * @return This object.
103    */
104   public McpCompletionRef setTarget(String value) {
105      target = value;
106      return this;
107   }
108}