Skip navigation.
Downloads | Product Documentation | Support

Programming Web Services for WebLogic Server

# WebLogic Web Service Deployment Descriptor Element Reference

The following sections provide information about the WebLogic-specific Web Services deployment descriptor file, `weblogic-webservices.xml`:

- Overview of weblogic-webservices.xml
- Graphical Representation
- XML Schema
- Example of a weblogic-webservices.xml Deployment Descriptor File
- Element Description

# Overview of weblogic-webservices.xml

The standard J2EE deployment descriptor for Web Services is called `webservices.xml`. This file specifies the set of Web Services that are to be deployed to WebLogic Server and the dependencies they have on container resources and other services. See the Web Services XML Schema for a full description of this file.

The WebLogic equivalent to the standard J2EE `webservices.xml` deployment descriptor file is called `weblogic-webservices.xml`. This file contains WebLogic-specific information about a WebLogic Web Service, such as the URL used to invoke the deployed Web Service, and so on.

Both deployment descriptor files are located in the same location on the J2EE archive that contains the Web Service. In particular:

- For Java class-implemented Web Services, the Web Service is packaged as a Web application WAR file and the deployment descriptors are located in the WEB-INF directory.
- For stateless session EJB-implemented Web Services, the Web Service is packaged as an EJB JAR file and the deployment descriptors are located in the META-INF directory.

The structure of the `weblogic-webservices.xml` file is similar to the structure of the J2EE `webservices.xml` file in how it lists and identifies the Web Services that are contained within the archive. For example, for each Web Service in the archive, both files have a `<webservice-description>` child element of the appropriate root element (`<webservices>` for the J2EE `webservices.xml` file and `<weblogic-webservices>` for the `weblogic-webservices.xml` file)

Typically users never need to update either deployment descriptor files, because the `jwsc` Ant task automatically generates the files for you based on the value of the JWS annotations in the JWS file that implements the Web Service. For this reason, this section is published for informational purposes only.

The data type definitions of two elements in the `weblogic-webservices.xml` file (login-config and transport-guarantee) are imported from the J2EE Schema for the`web.xml` file. See the Servlet Deployment Descriptor Schema for details about these elements and data types.

# Graphical Representation

The following graphic describes the element hierarchy of the `weblogic-webservices.xml` deployment descriptor file.

Figure 13-3 Element Hierarchy of weblogic-webservices.xml

# XML Schema

For the XML Schema file that describes the `weblogic-webservices.xml` deployment descriptor, see http://www.bea.com/ns/weblogic/90/weblogic-wsee.xsd.

# Example of a weblogic-webservices.xml Deployment Descriptor File

The following example shows a simple `weblogic-webservices.xml` deployment descriptor:

>     <?xml version='1.0' encoding='UTF-8'?>
>     <weblogic-webservices xmlns="http://www.bea.com/ns/weblogic/90">

>       <webservice-description>
>        <webservice-description-name>MyService</webservice-description-name>
>         <port-component>
>           <port-component-name>MyServiceServicePort</port-component-name>
>           <service-endpoint-address>
>             <webservice-contextpath>/MyService</webservice-contextpath>
>             <webservice-serviceuri>/MyService</webservice-serviceuri>
>           </service-endpoint-address>
>         </port-component>
>       </webservice-description>

>     </weblogic-webservices>

# Element Description

## deployment-listener-list

For internal use only.

## deployment-listener

For internal use only.

## exposed

Boolean attribute indicating whether the WSDL should be exposed to the public when the Web Service is deployed.

## login-config

The `j2ee:login-config` element specifies the authentication method that should be used, the realm name that should be used for this application, and the attributes that are needed by the form login mechanism.

The XML Schema data type of the `j2ee:login-config` element is `j2ee:login-configType`, and is defined in the J2EE Schema that describes the standard `web.xml` deployment descriptor. For the full reference information, see http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd.

## mbean-name

Specifies the name of the Web Service security configuration (specifically an instantiation of the `WebserviceSecurityMBean`) that is associated with the Web Services described in the deployment descriptor file. The default configuration is called `default_wss`.

The associated security configuration specifies information such as whether to use an X.509 certificate for identity, whether to use password digests, the keystore to be used for encryption and digital signatures, and so on.

You must create the security configuration (even the default one) using the Administration Console before you can successfully invoke the Web Service.

Note: The Web Service security configuration described by this element applies to all Web Services contained in the `weblogic-webservices.xml` file. The `jwsc` Ant task always packages a Web Service in its own JAR or WAR file, so this limation is not an issue if you always use the `jwsc` Ant task to generate a Web Service. However, if you update the `weblogic-webservices.xml` deployment descriptor manually and add additional Web Service descriptions, you cannot associate different security configurations to different services.

## port-component

The `<port-component>` element is a holder of other elements used to describe a Web Service port.

The child elements of the `<port-component>` element specify WebLogic-specific characteristics of the Web Service port, such as the context path and service URI used to invoke the Web Service after it has been deployed to WebLogic Server.

## port-component-name

The `<port-component-name>` child element of the `<port-component>` element specifies the internal name of the WSDL port.

The value of this element must be unique for all `<port-component-name>` elements within a single `weblogic-webservices.xml` file.

## service-endpoint-address

The `<service-endpoint-address>` element groups the WebLogic-specific context path and service URI values that together make up the Web Service endpoint address, or the URL that invokes the Web Service after it has been deployed to WebLogic Server.

These values are specified with the `<webservice-contextpath>` and `<webserivce-serviceuri>` child elements.

## transport-guarantee

The `j2ee:transport-guarantee` element specifies the type of communication between the client application invoking the Web Service and WebLogic server.

The value of this element is either NONE, INTEGRAL, or CONFIDENTIAL. NONE means that the application does not require any transport guarantees. A value of INTEGRAL means that the application requires that the data sent between the client and server be sent in such a way that it cannot be changed in transit. CONFIDENTIAL means that the application requires that the data be transmitted in a way that prevents other entities from observing the contents of the transmission. In most cases, the presence of the INTEGRAL or CONFIDENTIAL flag indicates that the use of SSL is required.

The XML Schema data type of the `j2ee:transport-guarantee` element is `j2ee:transport-guaranteeType`, and is defined in the J2EE Schema that describes the standard `web.xml` deployment descriptor. For the full reference information, see http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd.

## weblogic-webservices

The `<weblogic-webservices>` element is the root element of the WebLogic-specific Web Services deployment descriptor (`weblogic-webservices.xml`).

The element specifies the set of Web Services contained in the J2EE component archive in which the deployment descriptor is also contained. The archive is either an EJB JAR file (for stateless session EJB-implemented Web Services) or a WAR file (for Java class-implemented Web Services)

## webservice-contextpath

The `<webservice-contextpath>` element specifies the context path portion of the URL used to invoke the Web Service.

The URL to invoke a Web Service deployed to WebLogic Server is:

>     http://host:port/contextPath/serviceURI

where

- host is the host computer on which WebLogic Server is running.
- port is the port address to which WebLogic Server is listening.
- contextPath is the value of this element
- serviceURI is the value of the webservice-serviceuri element.

When using the `jwsc` Ant task to generate a Web Service from a JWS file, the value of the `<webservice-contextpath>` element is taken from the `contextPath` attribute of the WebLogic-specific `@WLHttpTransport` annotation or the `<WLHttpTransport>` child element of `jwsc`.

## webservice-description

The `<webservice-description>` element is a holder of other elements used to describe a Web Service.

The `<webservice-description>` element defines a set of port components (specified using one or more `<port-component>` child elements) that are associated with the WSDL ports defined in the WSDL document.

There may be multiple `<webservice-description>` elements defined within a single `weblogic-webservices.xml` file, each corresponding to a particular stateless session EJB or Java class contained within the archive, depending on the implementation of your Web Service. In other words, an EJB JAR contains the EJBs that implement a Web Service, a WAR file contains the Java classes.

## webservice-description-name

The `<webservice-description-name>` element specifies the internal name of the Web Service.

The value of this element must be unique for all `<webservice-description-name>` elements within a single `weblogic-webservices.xml` file.

## webservice-security

Element used to group together all the security-related elements of the `weblogic-webservices.xml` deployment descriptor.

## webservice-serviceuri

The `<webservice-serviceuri>` element specifies the Web Service URI portion of the URL used to invoke the Web Service.

The URL to invoke a Web Service deployed to WebLogic Server is:

>     http://host:port/contextPath/serviceURI

where

- host is the host computer on which WebLogic Server is running.
- port is the port address to which WebLogic Server is listening.
- contextPath is the value of the webservice-contextpath element
- serviceURI is the value of this element.

When using the `jwsc` Ant task to generate a Web Service from a JWS file, the value of the `<webservice-serviceuri>` element is taken from the `serviceURI` attribute of the WebLogic-specific `@WLHttpTransport` annotation or the `<WLHttpTransport>` child element of `jwsc`.

## wsdl

Element used to group together all the WSDL-related elements of the `weblogic-webservices.xml` deployment descriptor.

## wsdl-publish-file

The `<wsdl-publish-file>` element specifies a directory (on the computer which hosts the Web Service) to which WebLogic Server should publish a hard-copy of the WSDL file of a deployed Web Service; this is in addition to the standard WSDL file accessible via HTTP.

For example, assume that your Web Service is implemented with an EJB, and its WSDL file is located in the following directory of the EJB JAR file, relative to the root of the JAR:

>     META-INF/wsdl/a/b/Fool.wsdl

Further assume that the `weblogic-webservices.xml` file includes the following element for a given Web Service:

>     <wsdl-publish-file>d:/bar</wsdl-publish-file>

This means that when WebLogic Server deploys the Web Service, the server publishes the WSDL file at the standard HTTP location, but also puts a copy of the WSDL file in the following directory of the computer on which the service is running:

>     d:/bar/a/b/Foo.wsdl

Warning: Only specify this element if client applications that invoke the Web Service need to access the WSDL via the local file system or FTP; typically, client applications access the WSDL using HTTP, as described in Browsing to the WSDL of the Web Service.

The value of this element should be an absolute directory pathname. This directory must exist on every machine which hosts a WebLogic Server instance or cluster to which you deploy the Web Service.