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.Gone.*;
021
022import java.util.*;
023
024import org.apache.http.*;
025import org.apache.http.Header;
026import org.apache.juneau.commons.*;
027import org.apache.juneau.http.*;
028import org.apache.juneau.http.classic.*;
029import org.apache.juneau.http.classic.header.*;
030
031/**
032 * Exception representing an HTTP 410 ().
033 *
034 * <p>
035 * Indicates that the resource requested is no longer available and will not be available again.
036 * <br>This should be used when a resource has been intentionally removed and the resource should be purged.
037 * <br>Upon receiving a 410 status code, the client should not request the resource in the future.
038 * <br>Clients such as search engines should remove the resource from their indices.
039 * <br>Most use cases do not require clients and search engines to purge the resource, and a <js>"404 Not Found"</js> may be used instead.
040 *
041 * <h5 class='section'>See Also:</h5><ul>
042 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/JuneauRestCommon">juneau-rest-common</a>
043 * </ul>
044 *
045 * @serial exclude
046 */
047@Response
048@StatusCode(STATUS_CODE)
049@Schema(description = REASON_PHRASE)
050@SuppressWarnings({
051   "java:S110" // Inheritance depth acceptable for HTTP exception hierarchy
052})
053public class Gone extends BasicHttpException {
054   private static final long serialVersionUID = 1L;
055
056   /** HTTP status code */
057   public static final int STATUS_CODE = 410;
058
059   /** Reason phrase */
060   public static final String REASON_PHRASE = "Gone";
061
062   /** Default status line */
063   private static final BasicStatusLine STATUS_LINE = BasicStatusLine.create(STATUS_CODE, REASON_PHRASE);
064
065   /** Reusable unmodifiable instance */
066   public static final Gone INSTANCE = new Gone().unmodifiable();
067
068   /**
069    * Constructor.
070    */
071   public Gone() {
072      this((Throwable)null, REASON_PHRASE);
073   }
074
075   /**
076    * Constructor.
077    *
078    * <p>
079    * This is the constructor used when parsing an HTTP response.
080    *
081    * @param response The HTTP response to copy from.  Must not be <jk>null</jk>.
082    * @throws IllegalArgumentException If HTTP response status code does not match what was expected.
083    */
084   public Gone(HttpResponse response) {
085      super(requireStatus(response, STATUS_CODE));
086   }
087
088   /**
089    * Constructor.
090    *
091    * @param msg The message.  Can be <jk>null</jk>, in which case the reason phrase is used as the message.
092    * @param args Optional {@link String#format(String, Object...) String.format}-style arguments in the message.
093    */
094   public Gone(String msg, Object...args) {
095      this((Throwable)null, msg, args);
096   }
097
098   /**
099    * Constructor.
100    *
101    * @param cause The cause.  Can be <jk>null</jk>, in which case the reason phrase is used as the message and no cause is chained.
102    */
103   public Gone(Throwable cause) {
104      this(cause, cause == null ? REASON_PHRASE : cause.getMessage());
105   }
106
107   /**
108    * Constructor.
109    *
110    * @param cause The caused-by exception.  Can be <jk>null</jk> (no cause is chained).
111    * @param msg The message.  Can be <jk>null</jk>, in which case the cause's message is used, or the reason phrase if the cause is also <jk>null</jk> or has no message.
112    * @param args The message arguments.
113    */
114   public Gone(Throwable cause, String msg, Object...args) {
115      super(STATUS_CODE, cause, msg, args);
116      setStatusLine(STATUS_LINE.copy());
117   }
118
119   /**
120    * Copy constructor.
121    *
122    * @param copyFrom The bean to copy.  Must not be <jk>null</jk>.
123    */
124   protected Gone(Gone copyFrom) {
125      super(copyFrom);
126   }
127
128   /**
129    * Creates a modifiable copy of this bean.
130    *
131    * @return A new modifiable bean.
132    */
133   public Gone copy() {
134      return new Gone(this);
135   }
136
137   @Override /* Overridden from BasicHttpException */
138   public Gone setContent(HttpEntity value) {
139      super.setContent(value);
140      return this;
141   }
142
143   @Override /* Overridden from BasicHttpException */
144   public Gone setContent(String value) {
145      super.setContent(value);
146      return this;
147   }
148
149   @Override /* Overridden from BasicHttpException */
150   public Gone setHeader2(String name, Object value) {
151      super.setHeader2(name, value);
152      return this;
153   }
154
155   @Override /* Overridden from BasicHttpException */
156   public Gone setHeaders(HeaderList value) {
157      super.setHeaders(value);
158      return this;
159   }
160
161   @Override /* Overridden from BasicHttpException */
162   public Gone setHeaders(List<Header> values) {
163      super.setHeaders(values);
164      return this;
165   }
166
167   @Override /* Overridden from BasicHttpException */
168   public Gone setHeaders2(Header...values) {
169      super.setHeaders2(values);
170      return this;
171   }
172
173   @Override /* Overridden from BasicHttpException */
174   public Gone setLocale2(Locale value) {
175      super.setLocale2(value);
176      return this;
177   }
178
179   @Override /* Overridden from BasicRuntimeException */
180   public Gone setMessage(String message, Object...args) {
181      super.setMessage(message, args);
182      return this;
183   }
184
185   @Override /* Overridden from BasicHttpException */
186   public Gone setProtocolVersion(ProtocolVersion value) {
187      super.setProtocolVersion(value);
188      return this;
189   }
190
191   @Override /* Overridden from BasicHttpException */
192   public Gone setReasonPhrase2(String value) {
193      super.setReasonPhrase2(value);
194      return this;
195   }
196
197   @Override /* Overridden from BasicHttpException */
198   public Gone setReasonPhraseCatalog(ReasonPhraseCatalog value) {
199      super.setReasonPhraseCatalog(value);
200      return this;
201   }
202
203   @Override /* Overridden from BasicHttpException */
204   public Gone setStatusCode2(int code) throws IllegalStateException {
205      super.setStatusCode2(code);
206      return this;
207   }
208
209   @Override /* Overridden from BasicHttpException */
210   public Gone setStatusLine(BasicStatusLine value) {
211      super.setStatusLine(value);
212      return this;
213   }
214
215   @Override /* Overridden from BasicHttpException */
216   public Gone unmodifiable() {
217      return this instanceof UnmodifiableBean ? this : new Unmodifiable(this);
218   }
219
220   /**
221    * Unmodifiable point-in-time snapshot of the enclosing {@link Gone} exception.
222    *
223    * <p>
224    * Its only behavioral override is {@link #modify(Runnable)}, which throws — because all mutation is funneled through
225    * {@code modify(...)}, this single override freezes the entire mutation surface.
226    */
227   public static class Unmodifiable extends Gone implements UnmodifiableBean {
228
229      private static final long serialVersionUID = 1L;
230
231      /**
232       * Constructor.
233       *
234       * @param copyFrom The exception to snapshot.  Must not be <jk>null</jk>.
235       */
236      @SuppressWarnings({
237         "java:S1699" // Paradigm intentionally calls the overridable freeze() from the ctor to deep-freeze sub-beans.
238      })
239      protected Unmodifiable(Gone copyFrom) {
240         super(copyFrom);
241         freeze();
242      }
243
244      @Override /* Overridden from BasicHttpException */
245      protected BasicHttpException modify(Runnable mutation) {
246         throw uoex("Bean is unmodifiable.");
247      }
248   }
249}