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.http.classic.response;
018
019import static org.apache.juneau.commons.utils.Shorts.*;
020import static org.apache.juneau.http.classic.response.MultipleChoices.*;
021
022import org.apache.http.*;
023import org.apache.juneau.commons.*;
024import org.apache.juneau.http.*;
025import org.apache.juneau.http.classic.*;
026
027/**
028 * Represents an <c>HTTP 300 Multiple Choices</c> response.
029 *
030 * <p>
031 * Indicates multiple options for the resource from which the client may choose (via agent-driven content negotiation).
032 * For example, this code could be used to present multiple video format options, to list files with different filename extensions, or to suggest word-sense disambiguation.
033 *
034 * <h5 class='section'>See Also:</h5><ul>
035 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/JuneauRestCommon">juneau-rest-common</a>
036 * </ul>
037 */
038@Response
039@StatusCode(STATUS_CODE)
040@Schema(description = REASON_PHRASE)
041public class MultipleChoices extends BasicHttpResponse<MultipleChoices> {
042
043   /** HTTP status code */
044   public static final int STATUS_CODE = 300;
045
046   /** Reason phrase */
047   public static final String REASON_PHRASE = "Multiple Choices";
048
049   /** Default status line */
050   private static final BasicStatusLine STATUS_LINE = BasicStatusLine.create(STATUS_CODE, REASON_PHRASE);
051
052   /** Default unmodifiable instance */
053   public static final MultipleChoices INSTANCE = new MultipleChoices().unmodifiable();
054
055   /**
056    * Constructor.
057    */
058   public MultipleChoices() {
059      super(STATUS_LINE);
060   }
061
062   /**
063    * Constructor.
064    *
065    * <p>
066    * This is the constructor used when parsing an HTTP response.
067    *
068    * @param response The HTTP response to copy from.  Must not be <jk>null</jk>.
069    * @throws IllegalArgumentException If HTTP response status code does not match what was expected.
070    */
071   public MultipleChoices(HttpResponse response) {
072      super(requireStatus(response, STATUS_CODE));
073   }
074
075   /**
076    * Copy constructor.
077    *
078    * @param copyFrom The bean to copy from.  Must not be <jk>null</jk>.
079    */
080   public MultipleChoices(MultipleChoices copyFrom) {
081      super(copyFrom);
082   }
083
084   /**
085    * Creates a builder for this class initialized with the contents of this bean.
086    *
087    * @return A new builder bean.
088    */
089   public MultipleChoices copy() {
090      return new MultipleChoices(this);
091   }
092
093   @Override /* Overridden from BasicHttpResponse */
094   public MultipleChoices unmodifiable() {
095      return this instanceof UnmodifiableBean ? this : new Unmodifiable(this);
096   }
097
098   /**
099    * Unmodifiable point-in-time snapshot of the enclosing {@link MultipleChoices} response.
100    *
101    * <p>
102    * Its only behavioral override is {@link #modify(Runnable)}, which throws — because all mutation is funneled through
103    * {@code modify(...)}, this single override freezes the entire mutation surface.
104    */
105   public static class Unmodifiable extends MultipleChoices implements UnmodifiableBean {
106
107      /**
108       * Constructor.
109       *
110       * @param copyFrom The response to snapshot.  Must not be <jk>null</jk>.
111       */
112      @SuppressWarnings({
113         "java:S1699" // Paradigm intentionally calls the overridable freeze() from the ctor to deep-freeze sub-beans.
114      })
115      protected Unmodifiable(MultipleChoices copyFrom) {
116         super(copyFrom);
117         freeze();
118      }
119
120      @Override /* Overridden from BasicHttpResponse */
121      protected MultipleChoices modify(Runnable mutation) {
122         throw uoex("Bean is unmodifiable.");
123      }
124   }
125}