001// ***************************************************************************************************************************
002// * Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements.  See the NOTICE file *
003// * distributed with this work for additional information regarding copyright ownership.  The ASF licenses this file        *
004// * to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance            *
005// * with the License.  You may obtain a copy of the License at                                                              *
006// *                                                                                                                         *
007// *  http://www.apache.org/licenses/LICENSE-2.0                                                                             *
008// *                                                                                                                         *
009// * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an  *
010// * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the License for the        *
011// * specific language governing permissions and limitations under the License.                                              *
012// ***************************************************************************************************************************
013package org.apache.juneau.http.response;
014
015import static org.apache.juneau.http.response.Unauthorized.*;
016
017import java.text.*;
018import java.util.*;
019
020import org.apache.http.*;
021import org.apache.http.Header;
022import org.apache.juneau.annotation.*;
023import org.apache.juneau.http.*;
024import org.apache.juneau.http.annotation.*;
025import org.apache.juneau.http.header.*;
026import org.apache.juneau.internal.*;
027
028/**
029 * Exception representing an HTTP 401 (Unauthorized).
030 *
031 * <p>
032 * Similar to <c>403 Forbidden</c>, but specifically for use when authentication is required and has failed or has not yet been provided.
033 * <br>The response must include a WWW-Authenticate header field containing a challenge applicable to the requested resource.
034 * <br>401 semantically means "unauthenticated",i.e. the user does not have the necessary credentials.
035 * <br>Note: Some sites issue HTTP 401 when an IP address is banned from the website (usually the website domain) and that specific address is refused permission to access a website.
036 *
037 * <h5 class='section'>See Also:</h5><ul>
038 *    <li class='link'><a class="doclink" href="../../../../../index.html#juneau-rest-common">juneau-rest-common</a>
039 * </ul>
040 *
041 * @serial exclude
042 */
043@Response
044@StatusCode(STATUS_CODE)
045@Schema(description=REASON_PHRASE)
046@FluentSetters
047public class Unauthorized extends BasicHttpException {
048   private static final long serialVersionUID = 1L;
049
050   /** HTTP status code */
051   public static final int STATUS_CODE = 401;
052
053   /** Reason phrase */
054   public static final String REASON_PHRASE = "Unauthorized";
055
056   /** Default status line */
057   private static final BasicStatusLine STATUS_LINE = BasicStatusLine.create(STATUS_CODE, REASON_PHRASE);
058
059   /** Reusable unmodifiable instance */
060   public static final Unauthorized INSTANCE = new Unauthorized().setUnmodifiable();
061
062   /**
063    * Constructor.
064    *
065    * @param cause The caused-by exception.  Can be <jk>null</jk>.
066    * @param msg The message.  Can be <jk>null</jk>.
067    * @param args The message arguments.
068    */
069   public Unauthorized(Throwable cause, String msg, Object...args) {
070      super(STATUS_CODE, cause, msg, args);
071      setStatusLine(STATUS_LINE.copy());
072   }
073
074   /**
075    * Constructor.
076    */
077   public Unauthorized() {
078      this((Throwable)null, REASON_PHRASE);
079   }
080
081   /**
082    * Constructor.
083    *
084    * @param msg The message.  Can be <jk>null</jk>.
085    * @param args Optional {@link MessageFormat}-style arguments in the message.
086    */
087   public Unauthorized(String msg, Object...args) {
088      this((Throwable)null, msg, args);
089   }
090
091   /**
092    * Constructor.
093    *
094    * @param cause The cause.  Can be <jk>null</jk>.
095    */
096   public Unauthorized(Throwable cause) {
097      this(cause, cause == null ? REASON_PHRASE : cause.getMessage());
098   }
099
100   /**
101    * Constructor.
102    *
103    * <p>
104    * This is the constructor used when parsing an HTTP response.
105    *
106    * @param response The HTTP response to copy from.  Must not be <jk>null</jk>.
107    * @throws AssertionError If HTTP response status code does not match what was expected.
108    */
109   public Unauthorized(HttpResponse response) {
110      super(response);
111      assertStatusCode(response);
112   }
113
114   /**
115    * Copy constructor.
116    *
117    * @param copyFrom The bean to copy.
118    */
119   protected Unauthorized(Unauthorized copyFrom) {
120      super(copyFrom);
121   }
122
123   /**
124    * Creates a modifiable copy of this bean.
125    *
126    * @return A new modifiable bean.
127    */
128   public Unauthorized copy() {
129      return new Unauthorized(this);
130   }
131
132   // <FluentSetters>
133
134   @Override /* GENERATED - org.apache.juneau.BasicRuntimeException */
135   public Unauthorized setMessage(String message, Object...args) {
136      super.setMessage(message, args);
137      return this;
138   }
139
140   @Override /* GENERATED - org.apache.juneau.BasicRuntimeException */
141   public Unauthorized setUnmodifiable() {
142      super.setUnmodifiable();
143      return this;
144   }
145
146   @Override /* GENERATED - org.apache.juneau.http.response.BasicHttpException */
147   public Unauthorized setHeader2(String name, Object value) {
148      super.setHeader2(name, value);
149      return this;
150   }
151
152   @Override /* GENERATED - org.apache.juneau.http.response.BasicHttpException */
153   public Unauthorized setHeaders(HeaderList value) {
154      super.setHeaders(value);
155      return this;
156   }
157
158   @Override /* GENERATED - org.apache.juneau.http.response.BasicHttpException */
159   public Unauthorized setHeaders2(Header...values) {
160      super.setHeaders2(values);
161      return this;
162   }
163
164   @Override /* GENERATED - org.apache.juneau.http.response.BasicHttpException */
165   public Unauthorized setLocale2(Locale value) {
166      super.setLocale2(value);
167      return this;
168   }
169
170   @Override /* GENERATED - org.apache.juneau.http.response.BasicHttpException */
171   public Unauthorized setProtocolVersion(ProtocolVersion value) {
172      super.setProtocolVersion(value);
173      return this;
174   }
175
176   @Override /* GENERATED - org.apache.juneau.http.response.BasicHttpException */
177   public Unauthorized setReasonPhrase2(String value) {
178      super.setReasonPhrase2(value);
179      return this;
180   }
181
182   @Override /* GENERATED - org.apache.juneau.http.response.BasicHttpException */
183   public Unauthorized setReasonPhraseCatalog(ReasonPhraseCatalog value) {
184      super.setReasonPhraseCatalog(value);
185      return this;
186   }
187
188   @Override /* GENERATED - org.apache.juneau.http.response.BasicHttpException */
189   public Unauthorized setStatusCode2(int code) throws IllegalStateException{
190      super.setStatusCode2(code);
191      return this;
192   }
193
194   @Override /* GENERATED - org.apache.juneau.http.response.BasicHttpException */
195   public Unauthorized setStatusLine(BasicStatusLine value) {
196      super.setStatusLine(value);
197      return this;
198   }
199
200   // </FluentSetters>
201}