1 /*

     2  * Copyright (c) 2005, 2010, Oracle and/or its affiliates. All rights reserved.

     3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

     4  *

     5  * This code is free software; you can redistribute it and/or modify it

     6  * under the terms of the GNU General Public License version 2 only, as

     7  * published by the Free Software Foundation.  Oracle designates this

     8  * particular file as subject to the "Classpath" exception as provided

     9  * by Oracle in the LICENSE file that accompanied this code.

    10  *

    11  * This code is distributed in the hope that it will be useful, but WITHOUT

    12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

    13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

    14  * version 2 for more details (a copy is included in the LICENSE file that

    15  * accompanied this code).

    16  *

    17  * You should have received a copy of the GNU General Public License version

    18  * 2 along with this work; if not, write to the Free Software Foundation,

    19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

    20  *

    21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

    22  * or visit www.oracle.com if you need additional information or have any

    23  * questions.

    24  */

    25 

    26 package javax.xml.ws;

    27 

    28 import java.lang.annotation.Documented;

    29 import java.lang.annotation.ElementType;

    30 import java.lang.annotation.Retention;

    31 import java.lang.annotation.RetentionPolicy;

    32 import java.lang.annotation.Target;

    33 

    34 /**

    35  * The <code>FaultAction</code> annotation is used inside an {@link Action}

    36  * annotation to allow an explicit association of a WS-Addressing

    37  * <code>Action</code> message addressing property with the <code>fault</code>

    38  * messages of the WSDL operation mapped from the exception class.

    39  * <p>

    40  * The <code>wsam:Action</code> attribute value in the <code>fault</code>

    41  * message in the generated WSDL operation mapped for <code>className</code>

    42  * class is equal to the corresponding value in the <code>FaultAction</code>.

    43  * For the exact computation of <code>wsam:Action</code> values for the

    44  * fault messages, refer to the algorithm in the JAX-WS specification.

    45  *

    46  * <p>

    47  * <b>Example 1</b>: Specify explicit values for <code>Action</code> message addressing

    48  * property for the <code>input</code>, <code>output</code> and <code>fault</code> message

    49  * if the Java method throws only one service specific exception.

    50  *

    51  * <pre>

    52  * @WebService(targetNamespace="http://example.com/numbers")

    53  * public class AddNumbersImpl {

    54  *     @Action(

    55  *         fault = {

    56  *             <b>&#64;FaultAction(className=AddNumbersException.class, value="http://example.com/faultAction")</b>

    57  *         })

    58  *     public int addNumbers(int number1, int number2)

    59  *         throws AddNumbersException {

    60  *         return number1 + number2;

    61  *     }

    62  * }

    63  * </pre>

    64  *

    65  * The generated WSDL looks like:

    66  *

    67  * <pre>

    68  *   <definitions targetNamespace="http://example.com/numbers" ...>

    69  *     ...

    70  *     <portType name="AddNumbersPortType">

    71  *       <operation name="AddNumbers">

    72  *         ...

    73  *         <fault message="tns:AddNumbersException" name="AddNumbersException"

    74  *           <b>wsam:Action="http://example.com/faultAction"</b>/>

    75  *       </operation>

    76  *     </portType>

    77  *     ...

    78  *   </definitions>

    79  * </pre>

    80  *

    81  * <p>

    82  * Example 2: Here is an example that shows if the explicit value for <code>Action</code>

    83  * message addressing property for the service specific exception is not present.

    84  *

    85  * <pre>

    86  * @WebService(targetNamespace="http://example.com/numbers")

    87  * public class AddNumbersImpl {

    88  *     public int addNumbers(int number1, int number2)

    89  *         throws AddNumbersException {

    90  *         return number1 + number2;

    91  *     }

    92  * }

    93  * </pre>

    94  *

    95  * The generated WSDL looks like:

    96  *

    97  * <pre>

    98  *   <definitions targetNamespace="http://example.com/numbers" ...>

    99  *     ...

   100  *     <portType name="AddNumbersPortType">

   101  *       <operation name="AddNumbers">

   102  *         ...

   103  *         <fault message="tns:addNumbersFault" name="InvalidNumbers"

   104  *           <b>wsam:Action="http://example.com/numbers/AddNumbersPortType/AddNumbers/Fault/AddNumbersException"</b>/>

   105  *       </operation>

   106  *     </portType>

   107  *     ...

   108  *   </definitions>

   109  * </pre>

   110  *

   111  * <p>

   112  * Example 3: Here is an example that shows how to specify explicit values for <code>Action</code>

   113  * message addressing property if the Java method throws more than one service specific exception.

   114  *

   115  * <pre>

   116  * @WebService(targetNamespace="http://example.com/numbers")

   117  * public class AddNumbersImpl {

   118  *     @Action(

   119  *         fault = {

   120  *             <b>&#64;FaultAction(className=AddNumbersException.class, value="http://example.com/addFaultAction"),

   121  *             &#64;FaultAction(className=TooBigNumbersException.class, value="http://example.com/toobigFaultAction")</b>

   122  *         })

   123  *     public int addNumbers(int number1, int number2)

   124  *         throws AddNumbersException, TooBigNumbersException {

   125  *         return number1 + number2;

   126  *     }

   127  * }

   128  * </pre>

   129  *

   130  * The generated WSDL looks like:

   131  *

   132  * <pre>

   133  *   <definitions targetNamespace="http://example.com/numbers" ...>

   134  *     ...

   135  *     <portType name="AddNumbersPortType">

   136  *       <operation name="AddNumbers">

   137  *         ...

   138  *         <fault message="tns:addNumbersFault" name="AddNumbersException"

   139  *           <b>wsam:Action="http://example.com/addFaultAction"</b>/>

   140  *         <fault message="tns:tooBigNumbersFault" name="TooBigNumbersException"

   141  *           <b>wsam:Action="http://example.com/toobigFaultAction"</b>/>

   142  *       </operation>

   143  *     </portType>

   144  *     ...

   145  *   </definitions>

   146  * </pre>

   147  *

   148  * @since JAX-WS 2.1

   149  */

   150 

   151 @Documented

   152 @Retention(RetentionPolicy.RUNTIME)

   153 @Target(ElementType.METHOD)

   154 public @interface FaultAction {

   155     /**

   156      * Name of the exception class

   157      */

   158     Class<? extends Exception> className();

   159 

   160     /**

   161      * Value of WS-Addressing <code>Action</code> message addressing property for the exception

   162      */

   163     String value() default "";

   164 }