bea.com | products | dev2dev | support | askBEA

Download Docs | Site Map | Glossary
Search

Programming WebLogic Web Services

WebLogic Web Service Deployment Descriptor Elements

The web-services.xml deployment descriptor file contains information that describes one or more WebLogic Web services. This information includes details about the backend components that implement the operations of a Web service, the non-built-in data types used as parameters and return values, the SOAP message handlers that intercept SOAP messages, and so on. As is true for all deployment descriptors, web-services.xml is an XML file.

The following sections describe the web-services.xml file using different formats:

- "Graphical Representation" on page A-1

- "Element Reference" on page A-3

Graphical Representation

The following graphic describes the web-services.xml element hierarchy.

Element Reference

The following sectins, arranged alphabetically, describe each element in the web-services.xml file.

See Sample web-services.xml Files for sample Web services deployment descriptor files for a variety of different types of WebLogic Web services.

components

Defines the backend components that implement the Web service.

A WebLogic Web service can be implemented using one or more of the following components:

- Stateless session EJB

- JMS destination

- A Java class

This element has no attributes.

ejb-link

Identifies which EJB in an EJB JAR file is used to implement the stateless session EJB backend component.

Attribute | Description | Datatype | Required?
--- | --- | --- | ---
path | Name of the EJB in the form of: jar-name#ejb-name jar-name refers to the name of the JAR file, contained within the Web service EAR file, that contains the stateless session EJB. The name should include pathnames relative to the top level of the EAR file. ejb-name refers to the name of the stateless session EJB, corresponding to the <ejb-name> element in the ejb-jar.xml deployment descriptor file in the EJB JAR file. Example: myapp.jar#StockQuoteBean | String | Yes

fault

Specifies the SOAP fault that should be thrown if there is an error invoking this operation.

This element is not required.

Attribute | Description | Datatype | Required?
--- | --- | --- | ---
name | Name of the fault. | String | Yes
class-name | Fully qualified Java class that implements the SOAP fault. | String | Yes

handler

Describes a SOAP message handler in a handler chain. A single handler chain can consist of one or more handlers.

If the Java class that implements the handler expects initialization parameters, specify them using the optional <init-params> child element of the <handler> element.

Attribute | Description | Datatype | Required?
--- | --- | --- | ---
class-name | Fully qualified Java class that implements the SOAP message handler. | String | Yes

handler-chain

Lists the SOAP message handlers that make up a particular handler chain. A single WebLogic Web service can define zero or more handler chains.

The order in which the handlers (defined by the <handler> child element) are listed is important. By default, the handleRequest() methods of the handlers execute in the order that they are listed as child elements of the <handler-chain> element. The handleResponse() methods of the handlers execute in the reverse order that they are listed.

Attribute | Description | Datatype | Required?
--- | --- | --- | ---
name | Name of this handler chain. | String | Yes

handler-chains

Contains a list of <handler-chain> elements that describe the SOAP message handler chains used in the Web service described by this web-services.xml file. A single WebLogic Web service can define zero or more handler chains.

This element does not have any attributes.

init-param

Specifies a name-value pair that represents one of the initialization parameters of a handler.

Attribute | Description | Datatype | Required?
--- | --- | --- | ---
name | Name of the parameter. | String | Yes
value | Value of the parameter. | String | Yes

init-params

Contains the list of initialization parameters that are passed to the Java class that implements a handler.

This element does not have any attributes.

java-class

Describes the Java class component that implements one or more operations of a Web service.

Attribute | Description | Datatype | Required
--- | --- | --- | ---
name | Name of this component. | String | Yes
class-name | Fully qualified name of the Java class that implements this component. | String | Yes

jms-receive-queue

Specifies that one of the operations in the Web service is mapped to a JMS queue. Use this element to describe a Web service operation that receives data from a JMS queue.

Typically, a message producer puts a message on the specified JMS queue, and a client invoking this Web service operation polls and receives the message.

Attribute | Description | Datatype | Required?
--- | --- | --- | ---
name | Name of this component. | String | Yes
connection-factory | JNDI name of the JMS Connection factory that WebLogic Server uses to create a JMS Connection object. | String | Yes
provider-url | URL used to connect to a non-WebLogic Server JMS implementation. | String | No
initial-context-factory | Context factory for a non-WebLogic Server JMS implementation. | String | No

jms-receive-topic

Specifies that one of the operations in the Web service is mapped to a JMS topic. Use this element to describe a Web service operation that receives data from a JMS topic.

Typically, a message producer puts a message on the specified JMS topic, and a client invoking this Web service component polls and receives the message.

Attribute | Description | Datatype | Required?
--- | --- | --- | ---
name | Name of this component. | String | Yes
connection-factory | JNDI name of the JMS Connection factory that WebLogic Server uses to create a JMS Connection object. | String | Yes
provider-url | URL used to connect to a non-WebLogic Server JMS implementation. | String | No
initial-context-factory | Context factory for a non-WebLogic Server JMS implementation. | String | No

jms-send-destination

Specifies that one of the operations in the Web service is mapped to a JMS destination (either a queue or a topic). Use this element to describe a Web service operation that sends data to a JMS destination.

Typically, a message consumer (such as a message-driven bean) consumes the message after it is sent to the JMS destination.

Attribute | Description | Datatype | Required?
--- | --- | --- | ---
name | Name of this component. | String | Yes
connection-factory | JNDI name of the JMS Connection factory that WebLogic Server uses to create a JMS Connection object. | String | Yes
provider-url | URL used to connect to a non-WebLogic Server JMS implementation. | String | No
initial-context-factory | Context factory for a non-WebLogic Server JMS implementation. | String | No

jndi-name

Specifies a reference to an object bound into a JNDI tree. The reference can be to a stateless session EJB or to a JMS destination.

Attribute | Description | Datatype | Required?
--- | --- | --- | ---
path | Path name to the object from the JNDI context root. | String | Yes

operation

Configures a single operation of a Web service. Depending on the value and combination of attributes for this element, you can configure the following types of operations:

- An invoke of a method of a stateless session EJB or Java class. Specify this type of operation by setting the component attribute to the name of the stateless session EJB or Java class component and the method attribute to the name of the method.

- An invoke of a JMS backend component. Specify this type of operation by setting the component attribute to the name of the JMS component.

- The sequential invoke of the SOAP message handlers on a handler chain together with the invoke of a backend component. Specify this type of operation by setting the component attribute to the name of the component, and the handler-chain attribute to the name of the handler chain you want to invoke.

- The sequential invoke of the SOAP message handlers on a handler chain, but with no backend component. Specify this type of operation by just setting the handler-chain attribute to the name of the handler chain you want to invoke and not setting the component and method attributes.

Use the <params> child element to explicitly specify the parameters and return values of the operation.

Attribute | Description | Datatype | Required?
--- | --- | --- | ---
name | Name of the operation that will be used in the generated WSDL. If you do not specify this attribute, the name of the operation defaults to either the name of the method or the name of the SOAP message handler chain. | String | No
component | Name of the component that implements this operation. The value of this attribute corresponds to the name attribute of the appropriate <component> element. | String | No
> method | Name of the method of the EJB or Java class that implements the operation if you specify with the component attribute that the operation is implemented with a stateless session EJB or Java class. You can specify all the methods with the asterisk (*) character. If your EJB or Java class does not overload the method, you need only specify the name of the method, such as:
>     method="sell"
> If, however, the EJB or Java class overloads the method, then specify the full signature, such as:
>     method="sell(int)"
| String | No
handler-chain | Name of the SOAP message handler chain that implements the operation. The value of this attribute corresponds to the name attribute of the appropriate <handler-chain> element. | String | No
invocation-style | Specifies whether the operation both receives a SOAP request and sends a SOAP response, or whether the operation only receives a SOAP request but does not send back a SOAP response. This attribute accepts only two values: request-response (default value) or one-way. Note: If the backend component that implements this operation is a method of a stateless session EJB or Java class and you set this attribute to one-way, the method must return void | String | No
portTypeName | Port type in the WSDL file to which this operation belongs. You can include this operation in multiple port types by specifying a comma-separated list of port types. When the WSDL for this Web service is generated, a separate <portType> element is created for each specified port type. The default value is the value of the portType attribute of the <web-service> element. | String | No

operations

The <operations> element groups together the explicitly declared operations of this Web service.

This element does not have any attributes.

param

The <param> element specifies a single parameter of an operation.

You must list the parameters in the same order in which they are defined in the method that implements the operation. The number of <param> elements must match the number of parameters of the method.

Attribute | Description | Datatype | Required?
--- | --- | --- | ---
name | Name of the input parameter that will be used in the generated WSDL. If you do not specify this attribute, the parameter names are based on the data type of the parameter, such as intvalue1, intvalue2, traderesult, and so on. | String | No.
location | Part of the request SOAP message (either the header, the body, or the attachment) that contains the value of the input parameter. Valid values for this attribute are Body, Header, or attachment. The default value is Body. If you specify Body, the value of the parameter is extracted from the SOAP Body, according to regular SOAP rules for RPC operation invocation. If you specify Header, the value is extracted from a SOAP Header element whose name is the value of the type attribute. If you specify attachment, the value of the parameter is extracted from the SOAP Attachment rather than the SOAP envelope. As specified by the JAX-RPC specification, only the following Java data types can be extracted from the SOAP Attachment: java.awt.Image java.lang.String javax.mail.internet.MimeMultiport javax.xml.transform.Source javax.activation.DataHandler | String | No.
style | Style of the input parameter, either a standard input parameter, an out parameter used as a return value, or an in-out parameter for both inputting and outputting values. Valid values for this attribute are in, out, and in-out. If you specify a parameter as out or in-out, the Java class of the parameter in the backend component's method must implement the javax.xml.rpc.holders.Holder interface. | String | Yes.
type | XML Schema data type of the parameter. | NMTOKEN | Yes.
class-name | Java class name of the Java representation of the data type of the parameter. If you do not specify this attribute, WebLogic Server introspects the backend component that implements the operation for the Java class of the parameter. You are required to specify this attribute only if you want the mapping between the XML and Java representations of the parameter to be different than the default. For example, xsd:int maps to the Java primitive int type by default, so use this attribute to map it to java.lang.Integer instead. | NMTOKEN | Maybe. See the description of the attribute.

params

The <params> element groups together the explicitly declared parameters and return values of an operation.

You do not have to explicitly list the parameters or return values of an operation. If an <operation> element does not have a <params> child element, WebLogic Server introspects the backend component that implements the operation to determine its parameters and return values. When generating the WSDL file of the Web service, WebLogic Server uses the names of the corresponding method's parameters and return value.

You explicitly list an operation's parameters and return values when you want:

- The name of the parameters and return values in the generated WSDL to be different from those of the method that implements the operation.

- To map a parameter to a name in the SOAP header request or response.

- To use out or in-out parameters.

Use the <param> child element to specify the parameters of the operation.

Use the <return-param> child element to specify the return value of the operation.

The <params> element does not have any attributes.

return-param

The <return-param> element specifies the return value of the Web service operation.

You can specify only one <return-param> element for a given operation.

Attribute | Description | Datatype | Required?
--- | --- | --- | ---
name | Name of the return parameter that will be used in the generated WSDL file. If you do not specify this attribute, the return parameter is called result. | String | No.
location | Part of the response SOAP message (either the header or the body) that contains the value of the return parameter. Valid values for this attribute are Body or Header. The default value is Body. If you specify Body, the value of the return parameter will be added to the SOAP Body. If you specify Header, the value will added as a SOAP Header element whose name is the value of the type attribute. | String | No.
type | XML Schema data type of the return parameter. | NMTOKEN | Yes.
class-name | Java class name of the Java representation of the data type of the return parameter. If you do not specify this attribute, WebLogic Server introspects the backend component that implements the operation for the Java class of the return parameter. You are required to specify this attribute if: The backend component that implements the operation is either <jms-receive-queue> or <jms-receive-topic>. The mapping between the XML and Java representations of the return parameter is ambiguous, such as mapping xsd:int to either the int Java primitive type or java.lang.Integer. | NMTOKEN | Maybe. See the description of the attribute.

stateless-ejb

Describes the stateless session EJB component that implements one or more operations of a Web service.

Attribute | Description | Datatype | Required?
--- | --- | --- | ---
name | Name of the stateless EJB component. Note: The name is internal to the web-services.xml file; it does not refer to the name of the EJB in the ejb-jar.xml file. | String | Yes.

type-mapping

The <type-mapping> element contains the list of mappings between the XML data types defined in the <types> element and their Java representations.

For each data type in the <types> element, there is a corresponding <type-mapping-entry> element that lists the Java class that implements the data type, how to serialize and deserialize the data, and so on.

This element has no attributes.

type-mapping-entry

Describes the mapping between a single XML data type in the <types> element and its Java representation.

Attribute | Description | Datatype | Required?
--- | --- | --- | ---
class-name | Fully qualified name of the Java class that maps to its corresponding XML data type. | String | Yes.
element | Name of the XML data type that maps to the Java data type. Specify only if the XML Schema definition of the data type uses the <element> element. | NMTOKEN | One, but not both, of either element or type is required.
type | Name of the XML data type that maps to the Java data type. Specify only if the XML Schema definition of the data type uses the <type> element. | NMTOKEN | One, but not both, of either element or type is required.
serializer | Fully qualified name of the Java class that converts the data from Java to XML. | String | Only required if the data type is not one of the built-in data dates supported by the WebLogic Web services runtime, listed in Using Built-In Data Types.
deserializer | Fully qualified name of the Java class that converts the data from XML to Java. | String | Only required if the data type is not one of the built-in data dates supported by the WebLogic Web services runtime, listed in Using Built-In Data Types.

types

Describes, using XML Schema notation, the non-built-in data types used as parameters or return types of the Web service operations.

For details on using XML Schema to describe the XML representation of a non-built-in data type, see http://www.w3.org/TR/xmlschema-0/.

The following example shows an XML Schema declaration of a data type called TradeResult that contains two elements: stockSymbol, a string data type, and numberTraded, an integer.

>     <types>
>       <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
>                   xmlns:stns="java:examples.webservices"
>                   attributeFormDefault="qualified"
>                   elementFormDefault="qualified"
>                   targetNamespace="java:examples.webservices">
>           <xsd:complexType name="TradeResult">
>               <xsd:sequence>
>                   <xsd:element maxOccurs="1"
>                                name="stockSymbol"
>                                type="xsd:string" minOccurs="1">
>                   </xsd:element>
>                   <xsd:element maxOccurs="1"
>                                name="numberTraded"
>                                type="xsd:int"
>                                minOccurs="1">
>                   </xsd:element>
>               </xsd:sequence>
>           </xsd:complexType>
>       </xsd:schema>
>     </types>

web-service

Defines a single Web service.

The Web service is defined by the following:

- Backend components that implement an operation, such as a stateless session EJB, a Java class, or a JMS consumer or producer..

- An optional set of data type declarations for non-built-in data types used as parameters or return values to the Web service operations.

- An optional set of XML to Java data type mappings that specify the serialization class and Java classes for the non-built-in data types.

- A declaration of the operations supported by the Web service.

Attribute | Description | Datatype | Required?
--- | --- | --- | ---
name | Name of the Web service. | String | Yes.
targetNamespace | Namespace of this Web service. | String | Yes.
uri | URI of the Web service, used subsequently in the URL that invokes the Web service. Note: Be sure to specify the leading "/", such as /TraderService. | String | Yes.
protocol | Protocol over which the service is invoked. Valid values are http or https. Default is http. | String | No.
exposeHomePage | Specifies whether to publicly expose the Home Page of the Web Service. Valid values for this attribute are True and False. The default value is True. This means that by default the Home Page is publicly accessible. | Boolean | No.
exposeWSDL | Specifies whether to publicly expose the automatically generated WSDL of the Web Service. Valid values for this attribute are True and False. The default value is True. This means that by default the WSDL is publicly accessible. | Boolean | No.
style | Specifies whether the Web service has RPC-oriented or document-oriented operations. RPC-oriented WebLogic Web service operations use SOAP encoding. Document-oriented WebLogic Web service operations use literal encoding. Valid values are rpc and document. Default value is rpc. Warning: If you specify document for this attribute, all the methods that implement the operations of the Web service must have only one parameter. Note: Because the style attribute applies to an entire Web service, all operations specified in a single <web-service> element must be either RPC-oriented or documented-oriented; WebLogic Server does not support mixing the two styles within the same Web service. | String | No.
portName | Name of the <port> child element of the <service> element of the dynamically generated WSDL of this Web service. The default value is the name attribute of this element with Port appended. For example, if the name of this Web service is TraderService, the port name will be TraderServicePort. | String | No
portTypeName | Name of the default <portType> element in the dynamically generated WSDL of this Web service. The default value is the name attribute of this element with Port appended. For example, if the name of this Web service is TraderService, the portType name will be TraderServicePort. | String | No.
ignoreAuthHeader | Specifies that the Web Service ignore the Authorization HTTP header in the SOAP request. Note: Be careful using this attribute. If you set the value of this attribute to True, WebLogic Server never authenticates a client application that is attempting to invoke a Web Service, even if access control security constraints have been defined for the EJB, Web Application, or Enterprise Application that make up the Web Service. Or in other words, a client application that does not provide athentication credentials is still allowed to invoke a Web Service that has security constraints defined on it. Valid values are True and False. Default value is False. | Boolean. | No.

web-services

The root element of the web-services.xml deployment descriptor.

This element does not have any attributes.