1 /* 2 * Copyright (c) 2005, 2012, 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>@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>@FaultAction(className=AddNumbersException.class, value="http://example.com/addFaultAction"), 121 * @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 }