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.marshall.objecttools;
018
019import java.net.*;
020import org.apache.juneau.marshall.*;
021
022/**
023 * Generic exception thrown from the {@link PathTraversal} class.
024 *
025 * <p>
026 * Typically, this is a user-error, such as trying to address a non-existent node in the tree.
027 *
028 * <p>
029 * The status code is an HTTP-equivalent code.  It will be one of the following:
030 * <ul class='spaced-list'>
031 *    <li>
032 *       {@link HttpURLConnection#HTTP_BAD_REQUEST HTTP_BAD_REQUEST}
033 *       - Attempting to do something impossible.
034 *    <li>
035 *       {@link HttpURLConnection#HTTP_NOT_FOUND HTTP_NOT_FOUND}
036 *       - Attempting to access a non-existent node in the tree.
037 *    <li>
038 *       {@link HttpURLConnection#HTTP_FORBIDDEN HTTP_FORBIDDEN}
039 *       - Attempting to overwrite the root object.
040 * </ul>
041 *
042 *
043 * @serial exclude
044 */
045@SuppressWarnings({
046   "java:S110", // Deep inheritance inherent to the exception hierarchy
047   "java:S2166" // False positive: this IS an exception (BasicRuntimeException -> RuntimeException); name is correct public API.
048})
049public class PathTraversalException extends BasicRuntimeException {
050
051   private static final long serialVersionUID = 1L;
052
053   private final int status;
054
055   /**
056    * Constructor.
057    *
058    * @param status The HTTP-equivalent status code.
059    * @param message The detailed message.
060    * @param args Optional {@link String#format(String, Object...) String.format}-style arguments.
061    */
062   public PathTraversalException(int status, String message, Object...args) {
063      this(null, status, message, args);
064   }
065
066   /**
067    * Constructor.
068    *
069    * @param cause The cause of this exception.  Can be <jk>null</jk> (no cause is set).
070    * @param status HTTP status code.
071    * @param message The {@link String#format(String, Object...) String.format}-style message (<c>%s</c> placeholders).
072    * @param args Optional {@link String#format(String, Object...) String.format}-style arguments.
073    */
074   public PathTraversalException(Throwable cause, int status, String message, Object...args) {
075      super(cause, message, args);
076      this.status = status;
077   }
078
079   /**
080    * The HTTP-equivalent status code.
081    *
082    * <p>
083    * See above for details.
084    *
085    * @return The HTTP-equivalent status code.
086    */
087   public int getStatus() { return status; }
088
089   @Override /* Overridden from BasicRuntimeException */
090   public PathTraversalException setMessage(String message, Object...args) {
091      super.setMessage(message, args);
092      return this;
093   }
094}