1 /* 2 * Copyright (c) 1997, 2013, 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 com.sun.xml.internal.ws.api; 27 28 import com.sun.istack.internal.NotNull; 29 import com.sun.istack.internal.Nullable; 30 import com.sun.xml.internal.ws.api.addressing.AddressingVersion; 31 import com.sun.xml.internal.ws.api.message.Message; 32 import com.sun.xml.internal.ws.api.pipe.Codec; 33 import com.sun.xml.internal.ws.api.pipe.Tube; 34 35 import javax.xml.namespace.QName; 36 import javax.xml.ws.Binding; 37 import javax.xml.ws.WebServiceFeature; 38 import javax.xml.ws.handler.Handler; 39 import java.util.List; 40 import java.util.Set; 41 42 43 /** 44 * JAX-WS implementation of {@link Binding}. 45 * 46 * <p> 47 * This object can be created by {@link BindingID#createBinding()}. 48 * 49 * <p> 50 * Binding conceptually includes the on-the-wire format of the message, 51 * this this object owns {@link Codec}. 52 * 53 * @author Kohsuke Kawaguchi 54 */ 55 public interface WSBinding extends Binding { 56 /** 57 * Gets the SOAP version of this binding. 58 * 59 * TODO: clarify what to do with XML/HTTP binding 60 * 61 * <p> 62 * This is just a short-cut for {@code getBindingID().getSOAPVersion()} 63 * 64 * @return 65 * If the binding is using SOAP, this method returns 66 * a {@link SOAPVersion} constant. 67 * 68 * If the binding is not based on SOAP, this method 69 * returns null. See {@link Message} for how a non-SOAP 70 * binding shall be handled by {@link Tube}s. 71 */ 72 SOAPVersion getSOAPVersion(); 73 /** 74 * Gets the WS-Addressing version of this binding. 75 * <p/> 76 * TODO: clarify what to do with XML/HTTP binding 77 * 78 * @return If the binding is using SOAP and WS-Addressing is enabled, 79 * this method returns a {@link AddressingVersion} constant. 80 * If binding is not using SOAP or WS-Addressing is not enabled, 81 * this method returns null. 82 * 83 * This might be little slow as it has to go over all the features on binding. 84 * Its advisable to cache the addressingVersion wherever possible and reuse it. 85 */ 86 AddressingVersion getAddressingVersion(); 87 88 /** 89 * Gets the binding ID, which uniquely identifies the binding. 90 * 91 * <p> 92 * The relevant specs define the binding IDs and what they mean. 93 * The ID is used in many places to identify the kind of binding 94 * (such as SOAP1.1, SOAP1.2, REST, ...) 95 * 96 * @return 97 * Always non-null same value. 98 */ 99 @NotNull BindingID getBindingId(); 100 101 @NotNull@Override 102 List<Handler> getHandlerChain(); 103 104 /** 105 * Checks if a particular {@link WebServiceFeature} is enabled. 106 * 107 * @return 108 * true if enabled. 109 */ 110 boolean isFeatureEnabled(@NotNull Class<? extends WebServiceFeature> feature); 111 112 /** 113 * Experimental: Checks if a particular {@link WebServiceFeature} on an operation is enabled. 114 * 115 * @param operationName 116 * The WSDL name of the operation. 117 * @return 118 * true if enabled. 119 */ 120 boolean isOperationFeatureEnabled(@NotNull Class<? extends WebServiceFeature> feature, 121 @NotNull final QName operationName); 122 123 /** 124 * Gets a {@link WebServiceFeature} of the specific type. 125 * 126 * @param featureType 127 * The type of the feature to retrieve. 128 * @return 129 * If the feature is present and enabled, return a non-null instance. 130 * Otherwise null. 131 */ 132 @Nullable <F extends WebServiceFeature> F getFeature(@NotNull Class<F> featureType); 133 134 /** 135 * Experimental: Gets a {@link WebServiceFeature} of the specific type that applies to an operation. 136 * 137 * @param featureType 138 * The type of the feature to retrieve. 139 * @param operationName 140 * The WSDL name of the operation. 141 * @return 142 * If the feature is present and enabled, return a non-null instance. 143 * Otherwise null. 144 */ 145 @Nullable <F extends WebServiceFeature> F getOperationFeature(@NotNull Class<F> featureType, 146 @NotNull final QName operationName); 147 148 /** 149 * Returns a list of features associated with {@link WSBinding}. 150 */ 151 @NotNull WSFeatureList getFeatures(); 152 153 /** 154 * Experimental: Returns a list of features associated with {@link WSBinding} that apply to 155 * a particular operation. 156 * 157 * @param operationName 158 * The WSDL name of the operation. 159 */ 160 @NotNull WSFeatureList getOperationFeatures(@NotNull final QName operationName); 161 162 /** 163 * Experimental: Returns a list of features associated with {@link WSBinding} that apply to 164 * the input message of an operation. 165 * 166 * @param operationName 167 * The WSDL name of the operation. 168 */ 169 @NotNull WSFeatureList getInputMessageFeatures(@NotNull final QName operationName); 170 171 /** 172 * Experimental: Returns a list of features associated with {@link WSBinding} that apply to 173 * the output message of an operation. 174 * 175 * @param operationName 176 * The WSDL name of the operation. 177 */ 178 @NotNull WSFeatureList getOutputMessageFeatures(@NotNull final QName operationName); 179 180 /** 181 * Experimental: Returns a list of features associated with {@link WSBinding} that apply to 182 * one of the fault messages of an operation. 183 * 184 * @param operationName 185 * The WSDL name of the operation. 186 * @param messageName 187 * The WSDL name of the fault message. 188 */ 189 @NotNull WSFeatureList getFaultMessageFeatures(@NotNull final QName operationName, 190 @NotNull final QName messageName); 191 192 /** 193 * Returns set of header QNames known to be supported by this binding. 194 * @return Set of known QNames 195 */ 196 @NotNull Set<QName> getKnownHeaders(); 197 198 /** 199 * Adds header QName to set known to be supported by this binding 200 * @param knownHeader Known header QName 201 * @return true, if new entry was added; false, if known header QName was already known 202 */ 203 boolean addKnownHeader(QName knownHeader); 204 205 /** 206 * @return A MessageContextFactory configured according to the binding's features. 207 */ 208 @NotNull com.oracle.webservices.internal.api.message.MessageContextFactory getMessageContextFactory(); 209 }