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} annotation is used inside an {@link Action} 36 * annotation to allow an explicit association of a WS-Addressing 37 * {@code Action} message addressing property with the {@code fault} 38 * messages of the WSDL operation mapped from the exception class. 39 * <p> 40 * The {@code wsam:Action} attribute value in the {@code fault} 41 * message in the generated WSDL operation mapped for {@code className} 42 * class is equal to the corresponding value in the {@code FaultAction}. 43 * For the exact computation of {@code wsam:Action} 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} message addressing 48 * property for the {@code input}, {@code output} and {@code fault} message 49 * if the Java method throws only one service specific exception. 50 * 51 * <pre> 52 * {@literal @}WebService(targetNamespace="http://example.com/numbers") 53 * public class AddNumbersImpl { 54 * {@literal @}Action( 55 * fault = { 56 * <b>{@literal @}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> {@code 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>{@code /> 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} 83 * message addressing property for the service specific exception is not present. 84 * 85 * <pre> 86 * {@literal @}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>{@code 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>{@code /> 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} 113 * message addressing property if the Java method throws more than one service specific exception. 114 * 115 * <pre> 116 * {@literal @}WebService(targetNamespace="http://example.com/numbers") 117 * public class AddNumbersImpl { 118 * {@literal @}Action( 119 * fault = { 120 * <b>{@literal @}FaultAction(className=AddNumbersException.class, value="http://example.com/addFaultAction"), 121 * {@literal @}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> {@code 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>{@code /> 140 * <fault message="tns:tooBigNumbersFault" name="TooBigNumbersException"} 141 * <b>wsam:Action="http://example.com/toobigFaultAction"</b>{@code /> 142 * </operation> 143 * </portType> 144 * ... 145 * </definitions> 146 * }</pre> 147 * 148 * @since 1.6, 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} message addressing property for the exception 162 */ 163 String value() default ""; 164 }