Web Services Stack supports sending and receiving of messages over the following transports:
HTTP or HTTPS
TCP
JMS
By default, the HTTP transport is activated in all three Web Services Stack distributions (Web Services Stack in standalone server, Web Services Stack in web application, and Web Services Stack in Software AG Runtime). The HTTPS transport is activated by default only in the Web Services Stack in web application distribution, and needs to be explicitly enabled in the other installations. When you deploy a Web service archive file on the Web Services Stack runtime that runs on the Software AG Runtime server, service endpoints for all enabled transports are created automatically.
The following instructions show how to configure and activate or deactivate the other transports supported by Web Services Stack.
The information is organized under the following headings:
By default, the HTTP transport is activated in all three Web Services Stack distributions (Web Services Stack in standalone server, Web Services Stack in web application, and Web Services Stack in Software AG Runtime). The HTTPS transport is activated only in the Web Services Stack in web application distribution, and needs to be explicitly enabled in the other installations. The following procedure outlines the steps you must perform to enable or disable the HTTP and HTTPS transports.
Note:
If you disable a connector in Software AG Tomcat Server, make sure
that the respective transport sender and receiver are disabled on the Web
Services Stack side as well (axis2.xml). If a transport is
enabled in the axis2.xml file and the respective connector
in the server.xml file is disabled, an error occurs on the
Web Services Stack side.
Note:
Make sure at least one of your HTTPS connectors has the
description property set to "Default HTTPS
Connector". This value exists by default in the predefined HTTPS
connector definition. The "Default HTTPS Connector" value
is used by the Common Platform to distinguish default connectors from other
existing connectors. If this value is not present in at least one HTTPS
connector definition, this results in an invalid or corrupted Software AG
Runtime configuration the next time you install or upgrade a product in the
profile.
The information in this topic is organized under the following headings:
If you want to activate or deactivate HTTP or HTTPS in Web Services Stack, follow these steps:
To activate or deactivate HTTP or HTTPS in Web Services Stack
Go to the web application server where the Web Services Stack runtime is installed.
Open the axis2.xml configuration file in the webapps/wsstack/WEB-INF/conf directory for the Web Service Stack web application.
Note:
For Web Services Stack that uses Software AG Runtime Server the
axis2.xml file is in the following directory:
<Software
AG_directory>/profiles/CTP/workspace/wsstack/repository/conf/.
Comment out the sections that define the transport receiver and transport sender with name="http" or name="https":
<transportReceiver name="http" ... /> <transportSender name="http" ... />
<transportReceiver name="https" ... /> <transportSender name="https" ... />
Restart the Web Services Stack runtime for the modifications to take effect.
For Web Services Stack that uses Software AG Runtime Server, restart the "Software AG Runtime" Windows Service (using the Control Panel > Administrative Tools > Services).
If you want to activate or deactivate HTTP or HTTPS in Software AG Runtime server, follow these steps:
To activate or deactivate HTTP or HTTPS in Software AG Runtime
server
Open the server.xml configuration file under the <Software AG_directory>/profiles/CTP/configuration/tomcat/conf/ directory.
Comment out the sections that define the HTTP and HTTPS connectors, for example:
<clientAuth="false" sslProtocol="TLS" SSLEnabled="true" keystoreFile="C:/SoftwareAG/profiles/CTP/configuration/tomcat/conf/localhost_dont_use_in_production.jks" enabled="true" port="10011" keystorePass="change_this_password" scheme="https" enableLookups="false" secure="true" alias="defaultHttps" maxSpareThreads="75" maxThreads="150" server="SoftwareAG-Runtime" keystoreType="JKS" disableUploadTimeout="true" description="Default HTTPS Connector" algorithm="SunX509" minSpareThreads="25" acceptCount="100" maxHttpHeaderSize="8192"/>
Restart Software AG Runtime Server by restarting the "Software AG Runtime" Windows Service (using the Control Panel > Administrative Tools > Services).
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 for the Web Service Stack web application.
Note:
For Web Services Stack that uses Platform Tomcat Server the
axis2.xml file is in the following directory:
<Software
AG_directory>/profiles/CTP/workspace/wsstack/repository/conf/.
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 may not be 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 Designer
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 Designer plug-in, see Software AG Designer 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 Designer 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.
If you want to install and start a message broker, do the following:
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.
If you want to run the Active MQ Message Broker, follow these steps:
To run the ActiveMQ message broker
Open the command prompt
Navigate 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.
If you want to provide additional libraries for the Web Services Stack runtime, follow these steps:
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 for the Web Service Stack web application.
Note:
For Web Services Stack that uses Platform Tomcat Server the
axis2.xml file is in the following directory:
<Software
AG_directory>/profiles/CTP/workspace/wsstack/repository/conf/.
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.
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.
If you want to deploy over JMS transport only, follow this step:
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 Designer plug-in at deployment time by
selecting JMS Transport from the list of transports in the
Services tab.
You can specify a name for the connection factory that the Web service
will use. This can be done by modifying directly the
services.xml file, or by using the WSS Designer plug-in.
The parameters that define the connection factory name 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.
You can specify the connection factory name through the services.xml file by adding the elements in bold. The connection factory can be any of the connection factories defined in axis2.xml and the destination name can be anything. "transport.jms.ConnectionFactory" and "myQueueConnectionFactory" are samples for values of parameters.
<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>
You can also use the WSS Designer plug-in to specify the connection factory name.
To specify the connection factory name using the WSS Designer
plug-in
In the Project Explorer view, select the Web service archive that will use the connection factory.
Click the Services tab.
To specify the connection factory, in the Properties section:
Click .
Type "transport.jms.ConnectionFactory" in the Name field.
Type "myQueueConnectionFactory" (or another connection factory defined in axis2.xml) in the Value field.
Click .
To add the destinations:
Click .
Type "transport.jms.Destination" in the Name field.
Type "dynamicQueues/TestQueue" (or other value of your choice) in the Value field.
Click .
The connection factory name is now set and visible in the Services.xml tab.
For more information about working with the Web Services Stack Designer plug-in, see Software AG Designer 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.
If you want to install the Apache James Server, follow these steps:
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.
If you want to open the configuration files for editing, follow these steps:
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).
If you want to configure the DNS servers in the mail server, follow these steps:
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 following instructions and the description of the required parameters for the transport receiver and the transport sender.
To activate mail transport in Web Services Stack
Open the axis2.xml configuration file under the webapps/wsstack/WEB-INF/conf directory for the Web Service Stack web application.
Note:
For Web Services Stack that uses Platform Tomcat Server the
axis2.xml file is in the following directory:
<Software
AG_directory>/profiles/CTP/workspace/wsstack/repository/conf/.
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 parameters 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 parameters and its 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 the
|
| transport.mail.smtp.password |
Corresponds to the value of the
|
| mail.smtp.from |
Corresponds to the value of the
|
Following is a sample code listing of the usage of the required parameter 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>
