aoqi@0: /*
aoqi@0: * Copyright (c) 1997, 2013, Oracle and/or its affiliates. All rights reserved.
aoqi@0: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
aoqi@0: *
aoqi@0: * This code is free software; you can redistribute it and/or modify it
aoqi@0: * under the terms of the GNU General Public License version 2 only, as
aoqi@0: * published by the Free Software Foundation. Oracle designates this
aoqi@0: * particular file as subject to the "Classpath" exception as provided
aoqi@0: * by Oracle in the LICENSE file that accompanied this code.
aoqi@0: *
aoqi@0: * This code is distributed in the hope that it will be useful, but WITHOUT
aoqi@0: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
aoqi@0: * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
aoqi@0: * version 2 for more details (a copy is included in the LICENSE file that
aoqi@0: * accompanied this code).
aoqi@0: *
aoqi@0: * You should have received a copy of the GNU General Public License version
aoqi@0: * 2 along with this work; if not, write to the Free Software Foundation,
aoqi@0: * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
aoqi@0: *
aoqi@0: * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
aoqi@0: * or visit www.oracle.com if you need additional information or have any
aoqi@0: * questions.
aoqi@0: */
aoqi@0:
aoqi@0: package com.sun.xml.internal.ws.api;
aoqi@0:
aoqi@0: import com.sun.istack.internal.NotNull;
aoqi@0: import com.sun.istack.internal.Nullable;
aoqi@0: import com.sun.xml.internal.ws.api.addressing.AddressingVersion;
aoqi@0: import com.sun.xml.internal.ws.api.message.Message;
aoqi@0: import com.sun.xml.internal.ws.api.pipe.Codec;
aoqi@0: import com.sun.xml.internal.ws.api.pipe.Tube;
aoqi@0:
aoqi@0: import javax.xml.namespace.QName;
aoqi@0: import javax.xml.ws.Binding;
aoqi@0: import javax.xml.ws.WebServiceFeature;
aoqi@0: import javax.xml.ws.handler.Handler;
aoqi@0: import java.util.List;
aoqi@0: import java.util.Set;
aoqi@0:
aoqi@0:
aoqi@0: /**
aoqi@0: * JAX-WS implementation of {@link Binding}.
aoqi@0: *
aoqi@0: *
aoqi@0: * This object can be created by {@link BindingID#createBinding()}.
aoqi@0: *
aoqi@0: *
aoqi@0: * Binding conceptually includes the on-the-wire format of the message,
aoqi@0: * this this object owns {@link Codec}.
aoqi@0: *
aoqi@0: * @author Kohsuke Kawaguchi
aoqi@0: */
aoqi@0: public interface WSBinding extends Binding {
aoqi@0: /**
aoqi@0: * Gets the SOAP version of this binding.
aoqi@0: *
aoqi@0: * TODO: clarify what to do with XML/HTTP binding
aoqi@0: *
aoqi@0: *
aoqi@0: * This is just a short-cut for {@code getBindingID().getSOAPVersion()}
aoqi@0: *
aoqi@0: * @return
aoqi@0: * If the binding is using SOAP, this method returns
aoqi@0: * a {@link SOAPVersion} constant.
aoqi@0: *
aoqi@0: * If the binding is not based on SOAP, this method
aoqi@0: * returns null. See {@link Message} for how a non-SOAP
aoqi@0: * binding shall be handled by {@link Tube}s.
aoqi@0: */
aoqi@0: SOAPVersion getSOAPVersion();
aoqi@0: /**
aoqi@0: * Gets the WS-Addressing version of this binding.
aoqi@0: *
aoqi@0: * TODO: clarify what to do with XML/HTTP binding
aoqi@0: *
aoqi@0: * @return If the binding is using SOAP and WS-Addressing is enabled,
aoqi@0: * this method returns a {@link AddressingVersion} constant.
aoqi@0: * If binding is not using SOAP or WS-Addressing is not enabled,
aoqi@0: * this method returns null.
aoqi@0: *
aoqi@0: * This might be little slow as it has to go over all the features on binding.
aoqi@0: * Its advisable to cache the addressingVersion wherever possible and reuse it.
aoqi@0: */
aoqi@0: AddressingVersion getAddressingVersion();
aoqi@0:
aoqi@0: /**
aoqi@0: * Gets the binding ID, which uniquely identifies the binding.
aoqi@0: *
aoqi@0: *
aoqi@0: * The relevant specs define the binding IDs and what they mean.
aoqi@0: * The ID is used in many places to identify the kind of binding
aoqi@0: * (such as SOAP1.1, SOAP1.2, REST, ...)
aoqi@0: *
aoqi@0: * @return
aoqi@0: * Always non-null same value.
aoqi@0: */
aoqi@0: @NotNull BindingID getBindingId();
aoqi@0:
aoqi@0: @NotNull@Override
aoqi@0: List getHandlerChain();
aoqi@0:
aoqi@0: /**
aoqi@0: * Checks if a particular {@link WebServiceFeature} is enabled.
aoqi@0: *
aoqi@0: * @return
aoqi@0: * true if enabled.
aoqi@0: */
aoqi@0: boolean isFeatureEnabled(@NotNull Class feature);
aoqi@0:
aoqi@0: /**
aoqi@0: * Experimental: Checks if a particular {@link WebServiceFeature} on an operation is enabled.
aoqi@0: *
aoqi@0: * @param operationName
aoqi@0: * The WSDL name of the operation.
aoqi@0: * @return
aoqi@0: * true if enabled.
aoqi@0: */
aoqi@0: boolean isOperationFeatureEnabled(@NotNull Class feature,
aoqi@0: @NotNull final QName operationName);
aoqi@0:
aoqi@0: /**
aoqi@0: * Gets a {@link WebServiceFeature} of the specific type.
aoqi@0: *
aoqi@0: * @param featureType
aoqi@0: * The type of the feature to retrieve.
aoqi@0: * @return
aoqi@0: * If the feature is present and enabled, return a non-null instance.
aoqi@0: * Otherwise null.
aoqi@0: */
aoqi@0: @Nullable F getFeature(@NotNull Class featureType);
aoqi@0:
aoqi@0: /**
aoqi@0: * Experimental: Gets a {@link WebServiceFeature} of the specific type that applies to an operation.
aoqi@0: *
aoqi@0: * @param featureType
aoqi@0: * The type of the feature to retrieve.
aoqi@0: * @param operationName
aoqi@0: * The WSDL name of the operation.
aoqi@0: * @return
aoqi@0: * If the feature is present and enabled, return a non-null instance.
aoqi@0: * Otherwise null.
aoqi@0: */
aoqi@0: @Nullable F getOperationFeature(@NotNull Class featureType,
aoqi@0: @NotNull final QName operationName);
aoqi@0:
aoqi@0: /**
aoqi@0: * Returns a list of features associated with {@link WSBinding}.
aoqi@0: */
aoqi@0: @NotNull WSFeatureList getFeatures();
aoqi@0:
aoqi@0: /**
aoqi@0: * Experimental: Returns a list of features associated with {@link WSBinding} that apply to
aoqi@0: * a particular operation.
aoqi@0: *
aoqi@0: * @param operationName
aoqi@0: * The WSDL name of the operation.
aoqi@0: */
aoqi@0: @NotNull WSFeatureList getOperationFeatures(@NotNull final QName operationName);
aoqi@0:
aoqi@0: /**
aoqi@0: * Experimental: Returns a list of features associated with {@link WSBinding} that apply to
aoqi@0: * the input message of an operation.
aoqi@0: *
aoqi@0: * @param operationName
aoqi@0: * The WSDL name of the operation.
aoqi@0: */
aoqi@0: @NotNull WSFeatureList getInputMessageFeatures(@NotNull final QName operationName);
aoqi@0:
aoqi@0: /**
aoqi@0: * Experimental: Returns a list of features associated with {@link WSBinding} that apply to
aoqi@0: * the output message of an operation.
aoqi@0: *
aoqi@0: * @param operationName
aoqi@0: * The WSDL name of the operation.
aoqi@0: */
aoqi@0: @NotNull WSFeatureList getOutputMessageFeatures(@NotNull final QName operationName);
aoqi@0:
aoqi@0: /**
aoqi@0: * Experimental: Returns a list of features associated with {@link WSBinding} that apply to
aoqi@0: * one of the fault messages of an operation.
aoqi@0: *
aoqi@0: * @param operationName
aoqi@0: * The WSDL name of the operation.
aoqi@0: * @param messageName
aoqi@0: * The WSDL name of the fault message.
aoqi@0: */
aoqi@0: @NotNull WSFeatureList getFaultMessageFeatures(@NotNull final QName operationName,
aoqi@0: @NotNull final QName messageName);
aoqi@0:
aoqi@0: /**
aoqi@0: * Returns set of header QNames known to be supported by this binding.
aoqi@0: * @return Set of known QNames
aoqi@0: */
aoqi@0: @NotNull Set getKnownHeaders();
aoqi@0:
aoqi@0: /**
aoqi@0: * Adds header QName to set known to be supported by this binding
aoqi@0: * @param knownHeader Known header QName
aoqi@0: * @return true, if new entry was added; false, if known header QName was already known
aoqi@0: */
aoqi@0: boolean addKnownHeader(QName knownHeader);
aoqi@0:
aoqi@0: /**
aoqi@0: * @return A MessageContextFactory configured according to the binding's features.
aoqi@0: */
aoqi@0: @NotNull com.oracle.webservices.internal.api.message.MessageContextFactory getMessageContextFactory();
aoqi@0: }