Web Services Stack supports sending and receiving of messages over the following transports:
HTTP
TCP
JMS
HTTP is the single transport activated in the default Web Services Stack installation. The following instructions show how to configure and activate the other transports supported by Web Services Stack.
The information is organzied under the following headings:
There are no prerequisites for the activation of TCP transport.
To activate TCP transport in Web Services Stack
Go to the web application server where the Web Services Stack runtime is installed.
Open the axis2.xml configuration file under the /webapps/wsstack/WEB-INF/conf directory.
Uncomment the sections that define the transport receiver and transport sender with name="tcp":
<transportReceiver name="tcp" ... /> <transportSender name="tcp" ... />
The only parameter required for the transport receiver is its port number. The suggested default value is 6060.
Note:
Restart the Web Services Stack runtime for the modifications to take
effect.
Since the TCP transport has no application level headers (and no target endpoint URI), you need WS-Addressing to dispatch the service.
Note:
WS-Addressing is not enabled in the default Web Services Stack
installation.
To enable WS-Addressing
Engage the WS-Addressing module globally by adding in the axis2.xml configuration file the following line:
<module ref="addressing"/>
Or:
Engage the WS-Addressing module on a <service> level.
Engagement is for the service that is deployed on TCP transport.
You can enable WS-Addressing in the services.xml configuration file by adding the following line:
<service ...> <transports> <transport>tcp</transport> </transports> <module ref="addressing"/> ... </service>
Or:
Enable WS-Addressing by using the Web Services Stack Eclipse
plug-in. To do so, select Enable WS-Addressing from
the Modules list in the
tab.
For more information about working with the Web Services Stack Eclipse plug-in, see Eclipse Plug-in.
If not explicitly configured, a web service is deployed over all activated transports in the Web Services Stack runtime. In this case, the web service is accessible at all enabled endpoints.
You may, however, want to restrict a web service to be accessible only over TCP transport.
To deploy over TCP transport only
Configure the web service’s services.xml file by adding the following on the <service> level:
<service ...> <transports> <transport>tcp</transport> </transports> ... </service>
Or:
Use Web Services Stack Eclipse plug-in at deployment time.
To do this, select TCP Transport from the list of transports in the tab.
Note:
Since TCP transport has no application level headers, and thus no
target endpoint URI, you need WS-Addressing to dispatch the service. If
WS-Addressing is not globally enabled, you have to enable it for the
service.
To make a call to a web service over TCP transport, configure the client’s repository.
To invoke a web service over TCP
Uncomment the sections that define the transport receiver and transport sender with name=“tcp” in the client’s axis2.xml configuration file:
<transportReceiver name="tcp" ... /> <transportSender name="tcp" ... />
Engage globally the WS-Addressing module (addressing.mar) in the client’s axis2.xml file:
<module ref="addressing"/>
Ensure the WS-Addressing module (addressing.mar) is present in the /modules directory in the client’s repository.
Following are guidelines to the prerequisites for the activation of JMS transport.
To install and start a message broker
In order to achieve JMS communication, you need a message broker that handles the distribution of messages between communicating parties. Web Services Stack does not include a built-in message broker. This requires the use of an external one. Apache ActiveMQ is an open source message broker that you can download from http://activemq.apache.org/activemq-411-release.html.
Extract the files from the downloaded archive into a directory of your choice. For example, ACTIVEMQ_HOME.
After the installation, ActiveMQ is running with a basic configuration that is sufficient for its integration with the Web Services Stack.
Note:
If you want to terminate the broker, type the
CTRL-C command in the comand prompt in which it is
running.
Run the ActiveMQ message broker
Open the command prompt
Nnavigate to the ACTIVEMQ_HOME/bin directory
Run the activemq.bat file.
You can find more about installing and using Apache ActiveMQ open source message broker at http://activemq.apache.org/getting-started.html.
To provide additional libraries for the Web Services Stack
runtime
Configuring Web Services Stack to work with Apache ActiveMQ message broker requires the provision of additional libraries for the Web Services Stack runtime.
Go to the ACTIVEMQ_HOME/lib directory.
Copy the following libraries to the <web_app_server>/webapps/wsstack/WEB-INF/lib directory of the Web Services Stack runtime in the web application server:
activemq-core-4.1.1.jar
activeio-core-3.0.0-incubator.jar
geronimo-jms_1.1_spec-1.0.jar
geronimo-j2ee-management_1.0_spec-1.0.jar
Note:
You need those libraries for any client that invokes a service
over JMS transport.
To activate JMS transport in Web Services Stack
Go to the web application server, where the Web Services Stack runtime is installed
Open the axis2.xml configuration file under the /webapps/wsstack/WEB-INF/conf directory.
Uncomment the sections that define the transport receiver and
transport sender with name="jms":
<transportReceiver name="jms" ... /> <transportSender name="jms" ... />
Define the custom connection factories
You can define custom connection factories as parameters under JMS transport receiver. They can be used by the services deployed over JMS transport. Refer to the axis2.xml configuration file to see the sample connection factories that the JMS transport receiver configuration includes.
Note:
One of the connection factories is named as
default for use by services that do not explicitly
specify in their services.xml configuration file the
connection factory they want to use.
Those connection factories are associated with Apache ActiveMQ implementation whose libraries are required for the Web Services Stack runtime. Each connection factory specifies the following parameters:
An initial naming factory class
Naming provider URL
The JNDI name of an actual JMS connection factory.
Web Services Stack can run with the default configuration of Apache ActiveMQ. In this case, you only have to uncomment the JMS transport receiver and JMS transport sender configuration in the axis2.xml file.
Note:
You must always run the message broker before you start Web
Services Stack.
If not explicitly configured, a web service is deployed over all activated transports in the Web Services Stack runtime. However, you can restrict a web service to be deployed over JMS transport only.
To deploy over JMS transport only
Configure the web service’s services.xml file by adding the element in bold:
<service ...> <transports> <transport>jms</transport> </transports> ... </service>
Or:
Use Web Services Stack Eclipse plug-in at deployment time by
selecting JMS Transport from the list of transports in the
Services tab.
Note:
You can also specify the destination where the service listens for
messages, as well as the name of the connection factory to be used. The service
can use one of the connection factories defined within the JMS transport
receiver in the axis2.xml configuration file.
To specify the name of the connection factory
Configure the web service’s services.xml file by adding the element in bold:
<service ...> <transports> <transport>jms</transport> </transports> <parameter name="transport.jms.ConnectionFactory" locked="true">myQueueConnectionFactory</parameter> <parameter name="transport.jms.Destination" locked="true">dynamicQueues/TestQueue</parameter> ... </service>
Note:
Those values are samples. The connection factory can be any of
the connection factories defined in axis2.xml and the
destination name can be anything.
Or:
Use Web Services Stack Eclipse plug-in to add the two parameters in
the table in the section Properties in the
Services tab.
To use the Web Services Stack Eclipse plug-in to add the first of the
preceding parameters to the table in the section
Properties in the Services tab
Choose the button.
Type "transport.jms.ConnectionFactory" for name.
"myQueueConnectionFactory" (or another connection factory defined in axis2.xml) for value.
Select .
To use the Web Services Stack Eclipse plug-in to add the second of
the preceding parameters to the table in the section
Properties in the Services tab
Choose the button.
Type "transport.jms.Destination" for name.
"dynamicQueues/TestQueue" (or other value of your choice) for value.
Select .
Note:
These parameters are optional. If they are not specified, the
service uses the default connection factory (named as
default in the configuration of the JMS transport
receiver in the axis2.xml file) and listens for messages
on a JMS queue by the same name as the name of the service.
For more information about working with the Web Services Stack Eclipse plug-in, see Eclipse Plug-in.
To make a call to a web service over JMS transport, you have to configure the client’s repository.
To invoke a web service over JMS
Uncomment the sections that define the transport receiver and transport sender with name=“jms” in the client’s axis2.xml configuration file:
<transportReceiver name="jms" ... /> <transportSender name="jms" ... />
Engage globally the WS-Addressing module (addressing.mar) in the client’s axis2.xml file.
<module ref="addressing"/>
Ensure the WS-Addressing module (addressing.mar) is present in the /modules directory in the client’s repositor.
The information is organized under the following headings:
To activate mail transport in Web Services Stack, you need the following prerequisites:
The activation of mail transport in Web Services Stack requires a mail server that transfers e-mail messages. The Apache Java Enterprise Mail Server (James) is an open source SMTP and POP3 mail server that is used by Web Services Stack.
To install Apache James server
Download the archive with the binary distribution of the Apache James mail server from http://james.apache.org/download.cgi.
Extract the files from the downloaded archive to a JAMES_HOME directory of your choice.
Start and stop the mail server once so that it unpacks its configuration files.
To open the configuration files for editing
Open the command prompt.
Navigate to JAMES_HOME/bin directory.
Run run.bat to start the server.
Use the CTRL+C command to stop the mail
server.
Type the ipconfig/all command to check
your network configuration.
Note:
You need this information for the next instruction (configuring
the DNS servers).
To configure the DNS servers in the mail server
Open the config.xml file under the JAMES_HOME/apps/james/SAR-INF directory
Find the tag <dnsserver> and enter the IP address of each DNS server from your network configuration as shown in the following example:
<dnsserver> <servers> <server>[DNS.Server.IP.address]</server> <server>...</server> </servers> ... </dnsserver>
Note:
Apache James mail server requires the valid IP addresses of the
DNS servers in your network configuration.
Start the mail server again.
You can read more about the configuration of Apache James mail server in the "Configuring James" section of the James server documentation at http://james.apache.org/server/2.3.1/index.html.
After you have installed and configured your mail server, you have to create accounts. You need to create a mail account that represents the e-mail address of the Web Services Stack runtime. Additional accounts can be created to correspond to different clients.
To create an account
Start the Apache James mail server if it is not started.
To start Apache James Server, run the console command prompt, navigate to JAMES_HOME/bin directory and run run.bat.
Start James Remote Manager Service (this tool is used for administration purposes).
Run the console command prompt and type the following
telnet command:
telnet localhost 4555
Port number 4555 is the default port, where the Remote Manager Service starts. It is configured in the James configuration file (JAMES_HOME/apps/james/SAR-INF/config.xml). If you have changed the default port number in a previous step, use the new value in the preceding command
Log on the Remote Manager. You are prompted for the logon ID and password. They are configured in the James configuration file (JAMES_HOME/apps/james/SAR-INF/config.xml). The initial values are "root" for both, the ID and the password, unless you have changed them.
Type "root" for the logon ID and for the password.
Create the account. The command for adding a new user is
adduser username password. After executing the
command, you get a confirmation.
Type the following command:
adduser server wsstack
Exit the Remote Manager Service using the
quit command.
After you have executed the commands in the command prompt, you get a result similar to the following one:
>telnet localhost 4555 JAMES Remote Administration Tool 2.3.1 Please enter your login and password Login id: root Password: root Welcome root. HELP for a list of command adduser server wsstack User server added quit Bye
There are prerequisites for the activation of mail transport. Refer to the folowing instruction and the description of the required parameters for the transport receiver and the transport sender.
To activate mail transport in Web Services Stack
Go to the /webapps/wsstack/WEB-INF/conf directory.
Open the axis2.xml configuration file.
Configure the context root of Web Services Stack runtime.
In the axis2.xml file, find the parameter with
the name contextRoot. Uncomment it (if it is commented)
and ensure that its value is "wsstack":
<parameter name="contextRoot" locked="false">wsstack</parameter>
Activate the mail transport receiver and the mail transport sender.
In the axis2.xml file find and uncomment the sections that define the transport receiver and the transport sender with name=“mailto”:
<transportReceiver name="mailto" … /> <transportSender name="mailto" … />
The parameters under the transport receiver and the transport sender have fake default values. They need to be verified.
The following table lists the required paramters and their description:
| Parameter | Description |
|---|---|
| mail.pop3.host |
The host name (or IP address) where the James mail server is running. If the server is running on the same machine as the Web Services Stack runtime, then the value can be "localhost" or "127.0.0.1". |
| mail.pop3.user |
The user name of a user registered in the James mail server. The user name in the following sample code is the user registration from the example in the preceding topic "Creating accounts in the mail server". |
| transport.mail.pop3.password |
The user’s corresponding password for his account. |
| mail.store.protocol |
The value "pop3" is expected for that parameter. |
| transport.mail.replyToAddress |
This parameter is responsible for the followng values:
|
| transport.listener.interval |
Controls the time interval (in milliseconds) for checking the mail server for new messages. Note: |
Following is a sample code listing of the usage of the required parameters for the transport receiver:
<transportReceiver name="mailto" class="org.apache.axis2.transport.mail.SimpleMailListener"> <parameter name="mail.pop3.host">localhost</parameter> <parameter name="mail.pop3.user">server</parameter> <parameter name="transport.mail.pop3.password">wsstack</parameter> <parameter name="mail.store.protocol">pop3</parameter> <parameter name="transport.mail.replyToAddress">server@localhost</parameter> <parameter name="transport.listener.interval">3000</parameter> </transportReceiver>
The following table lists the required paramters and their description:
| Parameter | Description |
|---|---|
| mail.smtp.host |
The host name (or IP address), where James mail server is running. It corresponds to the |
| mail.smtp.user |
Corresponds to the value of
|
| transport.mail.smtp.password |
Corresponds to the value of
|
| mail.smtp.from |
Corresponds to the value of
|
Following is a sample code listing of the usage of the required parameters for the transport sender:
<transportSender name="mailto" class="org.apache.axis2.transport.mail.MailTransportSender"> <parameter name="mail.smtp.host" locked="false">localhost</parameter> <parameter name="mail.smtp.user">server</parameter> <parameter name="transport.mail.smtp.password">wsstack</parameter> <parameter name="mail.smtp.from">server@localhost</parameter> </transportSender>
If you want to restrict a web service to be deployed only over Mail transport, you must add the following element in the web service’s services.xml file:
<service ...> <transports> <transport>mailto</transport> </transports> ... </service>
Note:
If not configured explicitly, a web service is deployed over all
activated transports in the Web Services Stack runtime.
To call a web service over mail transport, configure the client’s repository.
To configure the client's repository
In the client’s axis2.xml configuration file, find and uncomment the sections that define the transport receiver and transport sender with name=“mailto”:
<transportReceiver name="mailto" ... /> <transportSender name="mailto" ... />
Check the parameters under the mail transport receiver and the mail transport sender. You must configure the user name, the password, and the e-mail address of a user registered in the James mail server. That user must be different from the one configured in the Web Services Stack runtime.
For details, see Activating Mail Transport.
Following is a sample code listing of client configuration with a user that is registered in the James mail server. The user name is "client" and the password is "pass":
<transportReceiver name="mailto" class="org.apache.axis2.transport.mail.SimpleMailListener"> <parameter name="mail.pop3.host">localhost</parameter> <parameter name="mail.pop3.user">client</parameter> <parameter name="mail.store.protocol">pop3</parameter> <parameter name="transport.mail.pop3.password">pass</parameter> <parameter name="transport.mail.replyToAddress">client@localhost</parameter> <parameter name="transport.listener.interval">3000</parameter> </transportReceiver> <transportSender name="mailto" class="org.apache.axis2.transport.mail.MailTransportSender"> <parameter name="mail.smtp.host">localhost</parameter> <parameter name="mail.smtp.user">client</parameter> <parameter name="transport.mail.smtp.password">pass</parameter> <parameter name="mail.smtp.from">client@localhost</parameter> </transportSender>
