-
Language:
English
-
Language:
English
Red Hat Training
A Red Hat training course is available for Red Hat Fuse
JBI Development Guide
Using the legacy Java Business Integration framework
Copyright © 2011-2014 Red Hat, Inc. and/or its affiliates.
Abstract
Part I. Introducing Java Business Integration
Abstract
Chapter 1. Introduction to JBI
Abstract
Figure 1.1. The JBI architecture
- The JBI component framework hosts and manages the JBI components. For more information see Chapter 2, The Component Framework.
- The normalized message router provides message mediation among the JBI components. For more information see Chapter 3, The Normalized Message Router.
- The management structure controls the life-cycle of the JBI components and the functional units deployed into the JBI components. It also provides mechanisms for monitoring the artifacts that are deployed into the JBI environment. For more information see Chapter 4, Management Structure.
Chapter 2. The Component Framework
Abstract
Overview
Component types
- Service Engine — Component that provides some of the logic required to provide services inside of the JBI environment. For example:
- message transformation
- orchestration
- advanced message routing
A service engine can communicate only with other components inside of the JBI environment. Service engines act as containers for the functional units deployed into the Red Hat JBoss Fuse. - Binding Component — Provides access to services outside the JBI environment using a particular protocol. Binding components implement the logic required to connect to a transport, and consume the messages received over that transport. Binding components are also responsible for the normalization of messages as they enter the JBI environment.
Packaging
META-INF/jbi.xml
. The packages differ based on the root element of the JBI descriptor and the contents of the package. The JBI environment uses four types of packaging to install and deploy functionality. The two most common types used by an application developer are:
- Service Assembly — A collection of service units. The root element of the JBI descriptor is a
service-assembly
element. The contents of the package is a collection of ZIP archives containing service units. The JBI descriptor specifies the target JBI component for each of the bundled service units. - Service Unit — A package that contains functionality to be deployed into a JBI component. For example, a service unit intended for a routing service engine contains the definition for one or more routes. Note that service units are packaged as a ZIP file. The root element of the JBI descriptor is a
service-unit
element. The contents of the package are specific to the service engine for which the service unit is intended.ImportantService units cannot be installed without being bundled into a service assembly.
Component roles
Chapter 3. The Normalized Message Router
Abstract
Overview
Message exchange patterns
- in-out
- A consumer sends a request message to a provider, which then responds to the request with a response message. The provider might also respond with a fault message if an error occured during processing.
- in-optional-out
- A consumer sends a request message to a provider. The provider might send a response message back to the consumer, but the consumer does not require a response. The provider might also respond with a fault message if an error occurred during processing. The consumer can also send a fault message to the provider.
- in-only
- A consumer sends a message to a provider, but the provider does not send a response, and, if an error occurs, the provider does not send fault messages back to the consumer.
- robust-in-only
- A consumer sends a message to a provider. The provider does not respond to the consumer except to send a fault message back to the consumer to signal an error condition.
Normalized messages
- meta-data, properties
- Holds information about the message. This information can include transaction contexts, security information, or other QoS information. The meta-data can also hold transport headers.
- payload
- An XML document that conforms to the XML Schema definition in the WSDL document that defines the message exchange. The XML document holds the substance of the message.
- attachments
- Hold any binary data associated with the message. For example, an attachment can be an image file sent as an attachment to a SOAP message.
- security
Subject
- Holds security information associated with the message, such as authentication credentials. For more information about the security
Sublect
, see Sun's API documentation.
Chapter 4. Management Structure
Abstract
Overview
JMX
MBean
interface.
Installing and uninstalling artifacts into the JBI Environment
- JBI components
- Shared libraries
- Service assemblies
- Service units
InstallationService
MBean that is exposed through the JMX console. In addition, the following Ant tasks are provided for installing and uninstalling JBI components and shared libraries:
- InstallComponentTask
- UninstallComponentTask
- InstallSharedLibraryTask
- UninstallSharedLibraryTask
DeploymentService
MBean that is exposed through the JMX console. In addition to the MBean, the following Ant tasks are provided for installing service assemblies and service units:
- DeployServiceAssemblyTask
- UndeployServiceAssemblyTask
Managing JBI components
Figure 4.1. JBI component life-cycle
InstallationService
MBean and the component's ComponentLifeCycle
MBean. In addition, you can manage a component's lifecycle using the following Ant tasks:
- StartComponentTask
- StopComponentTask
- ShutDownComponentTask
Managing service units
Figure 4.2. Service unit life-cycle
DeploymentService
MBean. In addition, you can manage service units using the following Ant tasks:
- DeployServiceAssemblyTask
- UndeployServiceAssemblyTask
- StartServiceAssemblyTask
- StopServiceAssemblyTask
- ShutDownServiceAssemblyTask
- ListServiceAssembliesTask
Chapter 5. Clustering JBI Endpoints
Overview
Features
- Connect JBI containers to form a network, and dynamically add and remove the containers from the network.
- Enable rollback and redelivery when a JBI exchange fails.
- Implement load balancing among JBI containers capable of handling a given exchange. For example:
- Install the same component in multiple JBI containers to provide increased capacity and high availability (if one container fails, the same component in another container can service the request).
- Partition the workload among multiple JBI container instances to enable different containers to handle different tasks, spreading the workload across multiple containers.
- Remote component awareness means each clustered JBI container is aware of the components in its peer containers. Networked containers listen for remote component registration/deregistration events and can route requests to those components.
Steps to set up clustering
- Install the jbi-cluster feature included in Red Hat JBoss Fuse. See the section called “Installing the clustering feature”.
- Optionally, configure the clustering engine with a JMS broker other than the Red Hat JBoss A-MQ. See the section called “Changing the JMS broker”.
- Optionally, change the default clustering engine configuration to specify different cluster and destination names. See the section called “Changing the default configuration”.
- Add endpoints and register the endpoint definition in the Spring configuration. See the section called “Using clustering in an application”.
Installing the clustering feature
- Start Red Hat JBoss Fuse.
- At the
JBossFuse:karaf@root>
prompt, type:features:install jbi-cluster
- Type
featuresL:list
to list the existing features and their installation state. Verify that the jbi-cluster feature is installed.
Default clustering engine configuration
jbi-cluster.xml
file in the org.apache.servicemix.jbi.cluster.config
bundle. This bundle is located in the installation directory in \system\org\apache\servicemix\jbi\cluster
.
Example 5.1. Default cluster engine configuration
<bean id="clusterEngine" class="org.apache.servicemix.jbi.cluster.engine.ClusterEngine"> <property name="pool"> <bean class="org.apache.servicemix.jbi.cluster.requestor.ActiveMQJmsRequestorPool"> <property name="connectionFactory" ref="connectionFactory" /> <property name="destinationName" value="${destinationName}" /> </bean> </property> <property name="name" value="${clusterName}" /> </bean> <osgi:list id="clusterRegistrations" interface="org.apache.servicemix.jbi.cluster.engine.ClusterRegistration" cardinality="0..N"> <osgi:listener ref="clusterEngine" bind-method="register" unbind-method="unregister" /> </osgi:list> <osgi:reference id="connectionFactory" interface="javax.jms.ConnectionFactory" /> <osgi:service ref="clusterEngine"> <osgi:interfaces> <value>org.apache.servicemix.nmr.api.Endpoint</value> <value>org.apache.servicemix.nmr.api.event.Listener</value> <value>org.apache.servicemix.nmr.api.event.EndpointListener</value> <value>org.apache.servicemix.nmr.api.event.ExchangeListener</value> </osgi:interfaces> <osgi:service-properties> <entry key="NAME" value="${clusterName}" /> </osgi:service-properties> </osgi:service> <osgix:cm-properties id="clusterProps" persistent-id="org.apache.servicemix.jbi.cluster.config"> <prop key="clusterName">${servicemix.name}</prop> <prop key="destinationName">org.apache.servicemix.jbi.cluster</prop> </osgix:cm-properties> <ctx:property-placeholder properties-ref="clusterProps" /> </beans>
Changing the default configuration
org.apache.servicemix.jbi.cluster.config
. This added configuration file enables you to change both the clusterName
and the destinationName
.
Changing the JMS broker
InstallDir\deploy
directory.
Using clustering in an application
Example 5.2. OSGi packaged JBI endpoint
<http:consumer id="myHttpConsumer" service="test:myService" endpoint="myEndpoint" /> <bean class="org.apache.servicemix.jbi.cluster.engine.OsgiSimpleClusterRegistration"> <property name="endpoint" ref="myHttpConsumer" /> </bean>
Example 5.3. JBI packaged endpoint
<http:consumer id="myHttpConsumer" service="test:myService" endpoint="myEndpoint" /> <bean class="org.apache.servicemix.jbi.cluster.engine.OsgiSimpleClusterRegistration"> <property name="serviceName" value="test:myService" /> <property name="endpointName" value="myEndpoint" /> </bean>
Establishing network connections between containers
- Static network connections — Configure each
networkConnector
in the cluster in the broker configuration fileinstall_dir/conf/activemq.xml
.Example 5.4 shows an example of a staticnetworkConnector
discovery configuration.Example 5.4. Static configuration
<!-- Set the brokerName to be unique for this container --> <amq:broker id="broker" brokerName="host1_broker1" depends-on="jmxServer"> .... <networkConnectors> <networkConnector name="host1_to_host2" uri="static://(tcp://host2:61616)"/> <!-- A three container network would look like this --> <!-- (Note it is not necessary to list the hostname in the uri list) --> <!-- networkConnector name="host1_to_host2_host3" uri="static://(tcp://host2:61616,tcp://host3:61616)"/ --> </networkConnectors> </amq:broker>
- Multicast network connections — Enable multicast on your network and configure multicast in the broker configuration file
installation_directory/conf/activemq.xml
for each container in the network. When the containers start they detect each other and transparently connect to one another.Example 5.5 shows an example of a multicastnetworkConnector
discovery configuration.Example 5.5. Multicast configuration
<networkConnectors> <!-- by default just auto discover the other brokers --> <networkConnector name="default-nc" uri="multicast://default"/> </networkConnectors>
High availability
ACTIVE
mode and the slave is in STANDBY
mode waiting for a failover event to trigger the slave to take over.
- Shared file system master-slave — In a shared database master-slave configuration, two containers use the same physical data store for the container state. You should ensure that the file system supports file level locking, as this is the mechanism used to elect the master. If the master process exits, the database lock is released and the slave acquires it. The slave then becomes the master.
- JDBC master-slave — In a JDBC master-slave configuration, the master locks a table in the backend database. The failover event in this case is that the lock is released from the database.
- Pure master-slave — A pure master-slave configuration can use either a shared database or a shared file system. The master replicates all state changes to the slave so additional overhead is incurred. The failover trigger in a pure master-slave configuration is that the slave loses its network connection to its master. Because of the additional overhead and maintenance involved, this option is less desirable than the other two options.
Cluster configuration conventions
- Don't use static and multicast
networkConnectors
at the same time. If you enable staticnetworkConnectors
, then you should disable any multicastnetworkConnectors
, and vice versa. - When configuring a network of containers in
installation_directory/conf/activemq.xml
, ensure that thebrokerName
attribute is unique for each node in the cluster. This will enable the instances in the network to uniquely identify each other. - When configuring a network of containers you must ensure that you have unique persistent stores for each
ACTIVE
instance. If you have a JDBC data source, you must use a separate database for eachACTIVE
instance. For example:<property name="url" value="jdbc:mysql://localhost/broker_activemq_host1?relaxAutoCommit=true"/>
- You can setup a network of containers on the same host. To do this, you must change the JMS ports and
transportConnector
ports to avoid any port conflicts. Edit theinstallation_directory/conf/activemq.xml
file, changing thermi.port
andactivemq.port
as appropriate. For example:rmi.port = 1098 rmi.host = localhost jmx.url = service:jmx:rmi:///jndi/rmi://${rmi.host}:${rmi.port}/jmxrmi activemq.port = 61616 activemq.host = localhost activemq.url = tcp://${activemq.host}:${activemq.port}
Chapter 6. Using the JBI Ant Tasks
6.1. Using the tasks as commands
Usage
ant
-f InstallDir/ant/servicemix-ant-tasks.xml
[
-Doption=value
...]
task
-Doption=value
flag.
Installing a component
Table 6.1. Options for installing a JBI component with an Ant command
Example 6.1. Installing a component using an Ant command
>
ant -f ant/servicemix-ant-task.xml -Dsm.port=1000 -Dsm.install.file=servicemix-camel-3.3.0.6-fuse-installer.zip install-component
Buildfile: ant\servicemix-ant-task.xml install-component: [echo] install-component [echo] Installing a service engine or binding component. [echo] host=localhost [echo] port=1000 [echo] file=hotdeploy\servicemix-camel-3.3.0.6-fuse-installer.zip BUILD SUCCESSFUL Total time: 7 seconds
Removing a component
Table 6.2. Options for removing a JBI component with an Ant command
Example 6.2. Removing a component using an Ant command
>
ant -f ant\servicemix-ant-task.xml -Dsm.port=1000 -Dsm.component.name=servicemix-drools uninstall-component
Buildfile: ant\servicemix-ant-task.xml uninstall-component: [echo] uninstall-component [echo] Uninstalling a Service Engine or Binding Component. [echo] host=localhost [echo] port=1000 [echo] name=servicemix-drools BUILD SUCCESSFUL Total time: 1 second
Starting a component
Table 6.3. Options for starting a JBI component with an Ant command
Example 6.3. Starting a component using an Ant command
>
ant -f ant\servicemix-ant-task.xml -Dsm.port=1000 -Dsm.component.name=servicemix-cxf-se start-component
Buildfile: ant\servicemix-ant-task.xml start-component: [echo] start-component [echo] starts a particular component (service engine or binding component) in Servicemix [echo] host=localhost [echo] port=1000 [echo] name=servicemix-cxf-se BUILD SUCCESSFUL Total time: 1 second
Stopping a component
Table 6.4. Options for stopping a JBI component with an Ant command
Example 6.4. Stopping a component using an Ant command
>
ant -f ant\servicemix-ant-task.xml -Dsm.port=1000 -Dsm.component.name=servicemix-cxf-se stop-component
Buildfile: ant\servicemix-ant-task.xml stop-component: [echo] stop-component [echo] stops a particular component (service engine or binding component) in Servicemix [echo] host=localhost [echo] port=1000 [echo] name=servicemix-cxf-se BUILD SUCCESSFUL Total time: 1 second
Shutting down a component
Table 6.5. Options for shutting down a JBI component with an Ant command
Installing a shared library
Table 6.6. Options for installing a shared library with an Ant command
Removing a shared library
Table 6.7. Options for removing a shared library with an Ant command
6.2. Using the tasks in build files
Adding the JBI tasks to build an Ant file
taskdef
element, as shown in Example 6.5.
Example 6.5. Adding the JBI tasks to an Ant build file
... <property name="fuseesb.install_dir" value="/home/fuse_esb"/> 1 <taskdef file="${fuseesb.install_dir}/ant/servicemix_ant_taskdef.properties"> 2 <classpath id="fuseesb.classpath"> 3 <fileset dir="${fuseesb.install_dir}"> <include name="*.jar"/> </fileset> <fileset dir="${fuseesb.install_dir}/lib"> <include name="*.jar"/> </fileset> </classpath> </taskdef> ...
Installing a component
jbi-install-component
. Its attributes are listed in Table 6.8.
Table 6.8. Attributes for installing a JBI component using an Ant task
Example 6.6. Ant target that installs a JBI component
... <target name="installDrools" description="Installs the drools engine."> <jbi-install-component port="1099" file="servicemix-drools-3.3.0.6-fuse-installer.zip" /> </target> ...
Removing a component
jbi-uninstall-component
. Its attributes are listed in Table 6.9.
Table 6.9. Attributes for removing a JBI component using an Ant task
Example 6.7. Ant target that removes a JBI component
... <target name="removeDrools" description="Removes the drools engine."> <jbi-uninstall-component port="1099" name="servicemix-drools" /> </target> ...
Starting a component
jbi-start-component
. Its attributes are listed in Table 6.10.
Table 6.10. Attributes for starting a JBI component using an Ant task
Example 6.8. Ant target that starts a JBI component
... <target name="startDrools" description="Starts the drools engine."> <jbi-start-component port="1099" name="servicemix-drools" /> </target> ...
Stopping a component
jbi-start-component
. Its attributes are listed in Table 6.11.
Table 6.11. Attributes for stopping a JBI component using an Ant task
Example 6.9. Ant target that stops a JBI component
... <target name="stopDrools" description="Stops the drools engine."> <jbi-stop-component port="1099" name="servicemix-drools" /> </target> ...
Shutting down a component
jbi-shut-down-component
. Its attributes are listed in Table 6.12.
Table 6.12. Attributes for shutting down a JBI component using an Ant task
Example 6.10. Ant target that shuts down a JBI component
... <target name="shutdownDrools" description="Stops the drools engine."> <jbi-shut-down-component port="1099" name="servicemix-drools" /> </target> ...
Installing a shared library
jbi-install-shared-library
. Its attributes are listed in Table 6.13.
Table 6.13. Attributes for installing a shared library using an Ant task
Removing a shared library
jbi-uninstall-shared-library
. Its attributes are listed in Table 6.14.
Table 6.14. Attributes for removing a shared library using an Ant task
Chapter 7. Building JBI Components Using Maven
Overview
- Plug-ins for packaging JBI components
- A plug-in for packaging shared libraries
- Archetypes that create starting point projects for JBI artifacts
Setting up the Maven tools
Example 7.1. POM elements for using Red Hat JBoss Fuse Maven tools
... <pluginRepositories> <pluginRepository> <id>fusesource.m2</id> <name>JBoss Fuse Open Source Community Release Repository</name> <url>http://repo.fusesource.com/maven2</url> <snapshots> <enabled>false</enabled> </snapshots> <releases> <enabled>true</enabled> </releases> </pluginRepository> </pluginRepositories> <repositories> <repository> <id>fusesource.m2</id> <name>JBoss Fuse Open Source Community Release Repository</name> <url>http://repo.fusesource.com/maven2</url> <snapshots> <enabled>false</enabled> </snapshots> <releases> <enabled>true</enabled> </releases> </repository> <repository> <id>fusesource.m2-snapshot</id> <name>JBoss Fuse Open Source Community Snapshot Repository</name> <url>http://repo.fusesource.com/maven2-snapshot</url> <snapshots> <enabled>true</enabled> </snapshots> <releases> <enabled>false</enabled> </releases> </repository> </repositories> ... <build> <plugins> <plugin> <groupId>org.apache.servicemix.tooling</groupId> <artifactId>jbi-maven-plugin</artifactId> <version>${servicemix-version}</version> <extensions>true</extensions> </plugin> </plugins> </build> ...
Creating a JBI Maven project
Example 7.2. Command for JBI maven archetypes
mvn
archetype:create
-DarchetypeGroupId=org.apache.servicemix.tooling
-DarchetypeArtifactId=servicemix-archetype-name
-DarchetypeVersion=fuse-4.0.0.0
[
-DgroupId=org.apache.servicemix.samples.embedded
] [
-DartifactId=servicemix-embedded-example
]
-DarchetypeArtifactId
argument specifies the type of project you are creating.
JBI components
jbi-component
for the project's packaging
element, which informs the Red Hat JBoss Fuse Maven tooling that the project is for a JBI component.
Example 7.3. Specifying that a maven project results in a JBI component
<project ...>
...
<groupId>org.apache.servicemix</groupId>
<artifactId>MyBindingComponent</artifactId>
<packaging>jbi-component</packaging>
...
</project>
plugin
element responsible for packaging the JBI component is shown in Example 7.4. The groupId
element, the artifactId
element, the version
element, and the extensions
element are common to all instances of the Red Hat JBoss Fuse Maven plug-in. If you use the Maven archetypes to generate the project, you should not have to change them.
Example 7.4. Plug-in specification for packaging a JBI component
... <plugin> <groupId>org.apache.servicemix.tooling</groupId> <artifactId>jbi-maven-plugin</artifactId> <version>${servicemix-version}</version> <extensions>true</extensions> <configuration> <type>service-engine</type> <bootstrap>org.apache.servicemix.samples.MyBootstrap</bootstrap> <component>org.apache.servicemix.samples.MyComponent</component> </configuration> </plugin> ...
configuration
element, along with its children, provides the Red Hat JBoss Fuse tooling with the metadata necessary to construct the jbi.xml
file required by the component.
-
type
- Specifies the type of JBI component the project is building. Valid values are:
service-engine
for creating a service enginebinding-component
for creating a binding component
-
bootstrap
- Specifies the name of the class that implements the JBI
Bootstrap
interface for the component.TipYou can omit this element if you intend to use the defaultBootstrap
implementation provided with Red Hat JBoss Fuse. -
component
- Specifies the name of the class that implements the JBI
Component
interface for that component.
Shared libraries
jbi-shared-library
for the project's packaging
element.
Example 7.5. Specifying that a maven project results in a JBI shared library
<project ...>
...
<groupId>org.apache.servicemix</groupId>
<artifactId>MyBindingComponent</artifactId>
<packaging>jbi-shared-library</packaging>
...
</project>
Chapter 8. Deploying JBI Endpoints Using Maven
Abstract
- Automatic generation of JBI descriptors
- Dependency checking
- Service assembly deployment
- Set up a top-level project to build all of the service units and the final service assembly (see Section 8.1, “Setting up a Red Hat JBoss Fuse JBI project”).
- Create a project for each of your service units (see Section 8.2, “A service unit project”).
- Create a project for the service assembly (see Section 8.3, “A service assembly project”).
8.1. Setting up a Red Hat JBoss Fuse JBI project
Overview
- It allows you to control the dependencies for all of the parts of an application in a central location.
- It limits the number of times you need to specify the proper repositories to load.
- It provides you a central location from which to build and deploy the application.
Directory structure
- A source directory containing the information required for the Maven assembly plug-in
- A directory to store the service assembly project
- At least one directory containing a service unit projectTipYou will need a project folder for each service unit that is to be included in the generated service assembly.
Setting up the Maven tools
Example 8.1. POM elements for using Red Hat JBoss Fuse Maven tooling
... <pluginRepositories> <pluginRepository> <id>fusesource.m2</id> <name>FuseSource Open Source Community Release Repository</name> <url>http://repo.fusesource.com/nexus/content/groups/public/</url> <snapshots> <enabled>false</enabled> </snapshots> <releases> <enabled>true</enabled> </releases> </pluginRepository> </pluginRepositories> <repositories> <repository> <id>fusesource.m2</id> <name>FuseSource Open Source Community Release Repository</name> <url>http://repo.fusesource.com/nexus/content/groups/public/</url> <snapshots> <enabled>false</enabled> </snapshots> <releases> <enabled>true</enabled> </releases> </repository> <repository> <id>fusesource.m2-snapshot</id> <name>FuseSource Open Source Community Snapshot Repository</name> <url>http://repo.fusesource.com/nexus/content/groups/public-snapshots/</url> <snapshots> <enabled>true</enabled> </snapshots> <releases> <enabled>false</enabled> </releases> </repository> </repositories> ... <build> <plugins> <plugin> <groupId>org.apache.servicemix.tooling</groupId> <artifactId>jbi-maven-plugin</artifactId> <version>servicemix-version</version> <extensions>true</extensions> </plugin> </plugins> </build> ...
Listing the sub-projects
modules
element. The modules
element contains one module
element for each service unit in the assembly. You also need a module
element for the service assembly.
Example JBI project pOM
Example 8.2. Top-level POM for a Red Hat JBoss Fuse JBI project
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd"> <modelVersion>4.0.0</modelVersion> <parent> <groupId>com.widgets</groupId> <artifactId>demos</artifactId> <version>1.0</version> </parent> <groupId>com.widgets.demo</groupId> <artifactId>cxf-wsdl-first</artifactId> <name>CXF WSDL Fisrt Demo</name> <packaging>pom</packaging> <pluginRepositories> 1 <pluginRepository> <id>fusesource.m2</id> <name>FuseSource Open Source Community Release Repository</name> <url>http://repo.fusesource.com/nexus/content/groups/public/</url> <snapshots> <enabled>false</enabled> </snapshots> <releases> <enabled>true</enabled> </releases> </pluginRepository> </pluginRepositories> <repositories> <repository> <id>fusesource.m2</id> <name>FuseSource Open Source Community Release Repository</name> <url>http://repo.fusesource.com/nexus/content/groups/public/</url> <snapshots> <enabled>false</enabled> </snapshots> <releases> <enabled>true</enabled> </releases> </repository> <repository> <id>fusesource.m2-snapshot</id> <name>FuseSource Open Source Community Snapshot Repository</name> <url>http://repo.fusesource.com/nexus/content/groups/public-snapshots/</url> <snapshots> <enabled>true</enabled> </snapshots> <releases> <enabled>false</enabled> </releases> </repository> </repositories> <modules> 2 <module>wsdl-first-cxfse-su</module> <module>wsdl-first-cxf-sa</module> </modules> <build> <plugins> <plugin> 3 <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-assembly-plugin</artifactId> <version>2.1</version> <inherited>false</inherited> <executions> <execution> <id>src</id> <phase>package</phase> <goals> <goal>single</goal> </goals> <configuration> <descriptors> <descriptor>src/main/assembly/src.xml</descriptor> </descriptors> </configuration> </execution> </executions> </plugin> <plugin> 4 <groupId>org.apache.servicemix.tooling</groupId> <artifactId>jbi-maven-plugin</artifactId> <extensions>true</extensions> </plugin> </plugins> </build> </project>
- 1
- Configures Maven to use the FuseSource repositories for loading the JBoss Fuse plug-ins.
- 2
- Lists the sub-projects used for this application. The
wsdl-first-cxfse-su
module is the module for the service unit. Thewsdl-first-cxf-sa
module is the module for the service assembly - 3
- Configures the Maven assembly plug-in.
- 4
- Loads the JBoss Fuse JBI plug-in.
8.2. A service unit project
Overview
Seeding a project using a Maven artifact
groupId
value and the artifactId
values correspond to the project's group ID and artifact ID.
Example 8.3. Maven archetype command for service units
smx-arch
su suArchetypeName
[
"-DgroupId=my.group.id"
] [
"-DartifactId=my.artifact.id"
]
"
) are required when using the -DgroupId
argument and the -DartifactId
argument.
Table 8.1. Service unit archetypes
Name | Description |
---|---|
camel | Creates a project for using the Apache Camel service engine |
cxf-se | Creates a project for developing a Java-first service using the Apache CXF service engine |
cxf-se-wsdl-first | Creates a project for developing a WSDL-first service using the Apache CXF service engine |
cxf-bc | Creates an endpoint project targeted at the Apache CXF binding component |
http-consumer | Creates a consumer endpoint project targeted at the HTTP binding component |
http-provider | Creates a provider endpoint project targeted at the HTTP binding component |
jms-consumer | Creates a consumer endpoint project targeted at the JMS binding component (see JBI Development Guide) |
jms-provider | Creates a provider endpoint project targeted at the JMS binding component (see JBI Development Guide) |
file-poller | Creates a polling (consumer) endpoint project targeted at the file binding component (see Chapter 10, Using Poller Endpoints) |
file-sender | Creates a sender (provider) endpoint project targeted at the file binding component (see Chapter 11, Using Sender Endpoints) |
ftp-poller | Creates a polling (consumer) endpoint project targeted at the FTP binding component |
ftp-sender | Creates a sender (provider) endpoint project targeted at the FTP binding component |
jsr181-annotated | Creates a project for developing an annotated Java service to be run by the JSR181 service engine [a] |
jsr181-wsdl-first | Creates a project for developing a WSDL generated Java service to be run by the JSR181 service engine [a] |
saxon-xquery | Creates a project for executing xquery statements using the Saxon service engine |
saxon-xslt | Creates a project for executing XSLT scripts using the Saxon service engine |
eip | Creates a project for using the EIP service engine. [b] |
lwcontainer | Creates a project for deploying functionality into the lightweight container [c] |
bean | Creates a project for deploying a POJO to be executed by the bean service engine |
ode | Create a project for deploying a BPEL process into the ODE service engine |
[a]
The JSR181 has been deprecated. The Apache CXF service engine has superseded it.
[b]
The EIP service engine has been deprecated. The Apache Camel service engine has superseded it.
[c]
The lightweight container has been deprecated.
|
Contents of a project
- a POM file that configures the JBI plug-in to create a service unit
- an XML configuration file stored in
src/main/resources
For many of the components, the XML configuration file is calledxbean.xml
. The Apache Camel component uses a file calledcamel-context.xml
.
Configuring the Maven plug-in
packaging
element to jbi-service-unit
as shown in Example 8.4.
Example 8.4. Configuring the maven plug-in to build a service unit
<project ...>
<modelVersion>4.0.0</modelVersion>
...
<groupId>com.widgets.demo.cxf-wsdl-first</groupId>
<artifactId>cxfse-wsdl-first-su</artifactId>
<name>CXF WSDL Fisrt Demo :: SE Service Unit</name>
<packaging>jbi-service-unit</packaging>
...
</project>
Specifying the target components
- List the targeted component as a dependency
- Add a
componentName
property specifying the targeted component
- Add a
componentName
property specifying the targeted component. - Add the remaining components to the list dependencies.
Example 8.5. Specifying the target components for a service unit
... <dependencies> <dependency> <groupId>org.apache.servicemix</groupId> <artifactId>servicemix-cxf-bc</artifactId> <version>3.3.1.0-fuse</version>[1] </dependency> >/dependencies> ...
componentName
element. This element is added to the standard Maven properties block and it specifies the name of a targeted component, as specified in Example 8.6.
Example 8.6. Specifying a target component for a service unit
... <properties> <componentName>servicemix-bean</componentName> </properties> ...
componentName
element, Maven does not check to see if the component is installed, nor does it download the required component.
Example
Example 8.7. POM file for a service unit project
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd"> <modelVersion>4.0.0</modelVersion> <parent> 1 <groupId>com.widgets.demo</groupId> <artifactId>cxf-wsdl-first</artifactId> <version>1.0</version> </parent> <groupId>com.widgets.demo.cxf-wsdl-first</groupId> <artifactId>cxfse-wsdl-first-su</artifactId> <name>CXF WSDL Fisrt Demo :: SE Service Unit</name> <packaging>jbi-service-unit</packaging> 2 <dependencies> 3 <dependency> <groupId>org.apache.servicemix</groupId> <artifactId>servicemix-cxf-bc</artifactId> <version>3.3.1.0-fuse</version> </dependency> >/dependencies> <build> <plugins> <plugin> 4 <groupId>org.apache.servicemix.tooling</groupId> <artifactId>jbi-maven-plugin</artifactId> <extensions>true</extensions> </plugin> </plugins> </build> </project>
- 1
- Specifies that it is a part of the top-level project shown in Example 8.2, “Top-level POM for a Red Hat JBoss Fuse JBI project”
- 2
- Specifies that this project builds a service unit
- 3
- Specifies that the service unit targets the Apache CXF binding component
- 4
- Specifies to use the Red Hat JBoss Fuse Maven plug-in
8.3. A service assembly project
Overview
Seeding a project using a Maven artifact
groupId
value and the artifactId
values, which correspond to the project's group ID and artifact ID.
Example 8.8. Maven archetype command for service assemblies
smx-arch
sa
[
"-DgroupId=my.group.id"
] [
"-DartifactId=my.artifact.id"
]
-DgroupId
argument and the -DartifactId
argument.
Contents of a project
Configuring the Maven plug-in
packaging
element to jbi-service-assembly
, as shown in Example 8.9.
Example 8.9. Configuring the Maven plug-in to build a service assembly
<project ...>
<modelVersion>4.0.0</modelVersion>
...
<groupId>com.widgets.demo.cxf-wsdl-first</groupId>
<artifactId>cxf-wsdl-first-sa</artifactId>
<name>CXF WSDL Fisrt Demo :: Service Assembly</name>
<packaging>jbi-service-assembly</packaging>
...
</project>
Specifying the target components
dependencies
element. Add a dependency
child element for each service unit. Example 8.10 shows the configuration for a service assembly that bundles two service units.
Example 8.10. Specifying the target components for a service unit
... <dependencies> <dependency> <groupId>com.widgets.demo.cxf-wsdl-first</groupId> <artifactId>cxfse-wsdl-first-su</artifactId> <version>1.0</version> </dependency> <dependency> <groupId>com.widgets.demo.cxf-wsdl-first</groupId> <artifactId>cxfbc-wsdl-first-su</artifactId> <version>1.0</version> </dependency> </dependencies> ...
Example
Example 8.11. POM for a service assembly project
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd"> <modelVersion>4.0.0</modelVersion> <parent> 1 <groupId>com.widgets.demo</groupId> <artifactId>cxf-wsdl-first</artifactId> <version>1.0</version> </parent> <groupId>com.widgets.demo.cxf-wsdl-first</groupId> <artifactId>cxf-wsdl-first-sa</artifactId> <name>CXF WSDL Fisrt Demo :: Service Assemby</name> <packaging>jbi-service-assembly</packaging> 2 <dependencies> 3 <dependency> <groupId>com.widgets.demo.cxf-wsdl-first</groupId> <artifactId>cxfse-wsdl-first-su</artifactId> <version>1.0</version> </dependency> <dependency> <groupId>com.widgets.demo.cxf-wsdl-first</groupId> <artifactId>cxfbc-wsdl-first-su</artifactId> <version>1.0</version> </dependency> </dependencies> <build> <plugins> <plugin> 4 <groupId>org.apache.servicemix.tooling</groupId> <artifactId>jbi-maven-plugin</artifactId> <extensions>true</extensions> </plugin> </plugins> </build> </project>
- 1
- Specifies that it is a part of the top-level project shown in Example 8.2, “Top-level POM for a Red Hat JBoss Fuse JBI project”
- 2
- Specifies that this project builds a service assembly
- 3
- Specifies the service units being bundled by the service assembly
- 4
- Specifies to use the JBoss Fuse Maven plug-in
Appendix A. Using the JBI Console Commands
Accessing the JBI commands
jbi:
then press Tab at the JBossFuse:karaf@root>
prompt to view the available commands.
Commands
Table A.1. JBI Commands
Command | Description |
---|---|
jbi:list | Lists all of the JBI artifacts deployed into the Red Hat JBoss Fuse container. The list is separated into JBI components and JBI service assemblies. It displays the name of the artifact and its life-cycle state. |
jbi:shutdown artifact | Moves the specified artifact from the stopped state to the shutdown state. |
jbi:stop artifact | Moves the specified artifact into the stopped state. |
jbi:start artifact | Moves the specified artifact into the started state. |
Part II. File Binding Component
Abstract
Chapter 9. Introduction to the File Binding Component
Abstract
Overview
- poller endpoint
- A poller endpoint polls a specified location on the file system for files. When it finds a file it reads the file and sends it to the NMR for delivery to the appropriate endpoint.ImportantA poller endpoint can only create in-only message exchanges.
- sender endpoint
- A sender endpoint receives messages from the NMR. It then writes the contents of the message to a specified location on the file system.
Key features
- custom filters for selecting files
- custom marshalers for converting the contents of a file to and from a normalized message
- custom locking mechanism for controlling file access during reads
- archiving of read files
Contents of a file component service unit
xbean.xml
- The
xbean.xml
file contains the XML configuration for the endpoint defined by the service unit. The contents of this file are the focus of this guide.NoteThe service unit can define more than one endpoint. meta-inf/jbi.xml
- The
jbi.xml
file is the JBI descriptor for the service unit. Example 9.1, “JBI descriptor for a file component service unit” shows a JBI descriptor for a file component service unit.Example 9.1. JBI descriptor for a file component service unit
<jbi xmlns="http://java.sun.com/xml/ns/jbi" version="1.0"> <services binding-component="false" /> </jbi>
TipThe developer typically does not need to hand code this file. It is generated by the Red Hat JBoss Fuse Maven tooling.
OSGi Packaging
- you will need to include an OSGi bundle manifest in the
META-INF
folder of the bundle. - You need to add the following to your service unit's configuration file:
<bean class="org.apache.servicemix.common.osgi.EndpointExporter" />
Namespace
http://servicemix.apache.org/file/1.0
namespace. You will need to add a namespace declaration similar to the one in Example 9.2, “Namespace declaration for using file endpoints” to your xbean.xml
file's beans
element.
Example 9.2. Namespace declaration for using file endpoints
<beans ...
xmlns:file="http://servicemix.apache.org/file/1.0"
... >
...
</beans>
beans
element's xsi:schemaLocation
as shown in Example 9.3, “Schema location for using file endpoints”.
Example 9.3. Schema location for using file endpoints
<beans ... xsi:schemaLocation="... http://servicemix.apache.org/file/1.0 http://servicemix.apache.org/file/1.0/servicemix-file.xsd ..."> ... </beans>
Chapter 10. Using Poller Endpoints
Abstract
10.1. Introduction to poller endpoints
Overview
Where does a poller endpoint fit into a solution?
Figure 10.1. Poller endpoint
Configuration element
poller
element. All its configuration can be specified using attributes of this element.
bean
elements or child elements of the poller
element.
10.2. Basic configuration
Overview
- the endpoint's name
- the endpoint's service name
- the file or directory to be monitored
- the endpoint to which the resulting messages will be sent
poller
element.
Identifying the endpoint
- a service name
- an endpoint name
Table 10.1. Attributes for identifying a poller endpoint
Specifying the message source
poller
element's file
attribute. This attribute takes a URI that identifies a location on the file system.
file
prefix, the endpoint will assume the URI specifies a directory on the file system and will consume all valid XML files placed in the specified directory.
inbox
. The URI inbox instructs the endpoint to poll the directory inbox
.
Specifying the target endpoint
- If you explicitly specify an endpoint using both the
targetService
attribute and thetargetEndpoint
attribute, the ESB will use that endpoint.ThetargetService
attribute specifies the QName of a service deployed into the ESB. ThetargetEndpoint
attribute specifies the name of an endpoint deployed by the service specified by thetargetService
attribute. - If you only specify a value for the
targetService
attribute, the NMR will attempt to find an appropriate endpoint on the specified service. - If you do not specify a service name or an endpoint name, you must specify the name of an interface that can accept the message using the
targetInterface
attribute. The NMR will attempt to locate an endpoint that implements the specified interface and direct the messages to it.Interface names are specified as QNames. They correspond to the value of thename
attribute of either a WSDL 1.1serviceType
element or a WSDL 2.0interface
element.
Example
Example 10.1. Simple poller endpoint
<beans xmlns:file="http://servicemix.apache.org/file/1.0" xmlns:foo="http://servicemix.org/demo/"> <file:poller service="foo:filePoller" endpoint="filePoller" targetService="foo:fileSender" file="file:inbox/test.xml" /> ... </beans>
10.3. Configuring poller endpoints interactions with the file system
Overview
- if the endpoint creates the directory it is configured to poll
- if the endpoint polls the subdirectories of the configured directory
- if the endpoint deletes the files it consumes
- where the endpoint archives copies of the consumed files
Directory handling
autoCreateDirectory
attribute to false
. If the directory does not exist, the endpoint will do nothing. You will then have to create the directory manually.
recursive
attribute to false
.
Example 10.2. Poller endpoint that does not check subdirectories
<beans xmlns:file="http://servicemix.apache.org/file/1.0"
xmlns:foo="http://servicemix.org/demo/">
<file:poller service="foo:filePoller"
endpoint="filePoller"
targetService="foo:fileSender"
file="inbox"
recursive="false" />
...
</beans>
File retention
deleteFile
attribute to false
.
Example 10.3. Poller endpoint that leaves files behind
<beans xmlns:file="http://servicemix.apache.org/file/1.0"
xmlns:foo="http://servicemix.org/demo/">
<file:poller service="foo:filePoller"
endpoint="filePoller"
targetService="foo:fileSender"
file="inbox"
deleteFile="false" />
...
</beans>
Archiving files
archive
attribute. The value of the archive
attribute is a URI pointing to the directory into which the consumed files will archived.
archives
.
Example 10.4. Poller endpoint that archives files
<beans xmlns:file="http://servicemix.apache.org/file/1.0"
xmlns:foo="http://servicemix.org/demo/">
<file:poller service="foo:filePoller"
endpoint="filePoller"
targetService="foo:fileSender"
file="inbox"
archive="archives" />
...
</beans>
10.4. Configuring the Polling Interval
Overview
Scheduling the first poll
firstTime
attribute. The firstTime
attribute specifies a date using the standard xsd:date format of YYYY-MM-DD
. For example, you would specify April 1, 2025 as 2025-04-01
. The first polling attempt will be made at 00:00:00 GMT on the specified date.
Example 10.5. Poller endpoint with a scheduled start time
<beans xmlns:file="http://servicemix.apache.org/file/1.0"
xmlns:foo="http://servicemix.org/demo/">
<file:poller service="foo:filePoller"
endpoint="filePoller"
targetService="foo:fileSender"
file="inbox"
firstTime="2010-04-01" />
...
</beans>
Delaying the first poll
delay
attribute which specifies the delay interval in milliseconds.
Example 10.6. Poller endpoint with a delayed start time
<beans xmlns:file="http://servicemix.apache.org/file/1.0"
xmlns:foo="http://servicemix.org/demo/">
<file:poller service="foo:filePoller"
endpoint="filePoller"
targetService="foo:fileSender"
file="inbox"
delay="300000" />
...
</beans>
Configuring the polling interval
period
attribute. The period
attribute specifies the number of milliseconds the endpoint waits between polling attempts.
Example 10.7. Poller Endpoint with a thirty second polling interval
<beans xmlns:file="http://servicemix.apache.org/file/1.0"
xmlns:foo="http://servicemix.org/demo/">
<file:poller service="foo:filePoller"
endpoint="filePoller"
targetService="foo:fileSender"
file="inbox"
period="30000" />
...
</beans>
10.5. File locking
Overview
org.apache.servicemix.common.locks.LockManager
interface. By default, poller endpoints use a provided implementation of this interface. If the default behavior is not appropriate for your application, you can implement the LockManager
interface and configure your endpoints to use your implementation.
Implementing a lock manager
org.apache.servicemix.common.locks.LockManager
interface. The LockManager
has single method, getLock()
that needs to be implemented. Example 10.8, “The lock manager's get lock method” shows the signature for getLock()
.
Example 10.8. The lock manager's get lock method
Lock getLock(String id);
getLock()
method takes a string that represents the URI of the file being processes and it returns a java.util.concurrent.locks.Lock
object. The returned Lock
object holds the lock for the specified file.
Example 10.9. Simple lock manager implementation
package org.apache.servicemix.demo; import java.util.concurrent.ConcurrentHashMap; import java.util.concurrent.ConcurrentMap; import java.util.concurrent.locks.Lock; import java.util.concurrent.locks.ReentrantLock; import org.apache.servicemix.common.locks.LockManager; public class myLockManager implements LockManager { private ConcurrentMap<String, Lock> locks = new ConcurrentHashMap<String, Lock>(); public Lock getLock(String id) { Lock lock = locks.get(id); if (lock == null) { lock = new ReentrantLock(); Lock oldLock = locks.putIfAbsent(id, lock); if (oldLock != null) { lock = oldLock; } } return lock; } }
Configuring the endpoint to use a lock manager
lockManager
attribute. The lockManager
attribute's value is a reference to a bean
element specifying the class of your custom lock manager implementation.
Example 10.10. Poller endpoint using a custom lock manager
<beans xmlns:file="http://servicemix.apache.org/file/1.0" xmlns:foo="http://servicemix.org/demo/"> <file:poller service="foo:filePoller" endpoint="filePoller" targetService="foo:fileSender" file="inbox" lockManager="#myLockManager" /> <bean id="myLockManager" class="org.apache.servicemix.demo.myLockManager" /> ... </beans>
lockManager
element to the endpoint's configuration. The lockManager
element simply wraps the bean
element that configures the lock manager.
10.6. File filtering
Overview
java.io.FileFilter
interface.
Implementing a file filter
java.io.FileFilter
interface. The FileFilter
interface has a single method, accept()
, that needs to be implemented. Example 10.11, “File filter's accept method” shows the signature of the accept()
method.
Example 10.11. File filter's accept method
public boolean accept()(java.io.File pathname);
accept()
method takes a File
object that represents the file being checked against the filter. If the file passes the filter, the accept()
method should return true
. If the file does not pass, then the method should return false
.
Example 10.12. Simple file filter implementation
package org.apache.servicemix.demo; import java.io.File; import java.io.FileFilter; public class myFileFilter implements FileFilter { String filtername = "joe.xml"; public myFileFilter() { } public myFileFilter(String filtername) { this.filtername = filtername; } public boolean accept(File file) { String name = file.getName(); return name.equals(this.filtername); } }
Configuring an endpoint to use a file filter
filter
attribute. The filter
attribute's value is a reference to a bean
element specifying the class of the file filter implementation.
constructor-arg
element sets the filter's fitlername by passing a value into the constructor.
Example 10.13. Poller endpoint using a file filter
<beans xmlns:file="http://servicemix.apache.org/file/1.0" xmlns:foo="http://servicemix.org/demo/"> <file:poller service="foo:filePoller" endpoint="filePoller" targetService="foo:fileSender" file="inbox" filter="#myFilter" /> <bean id="myFilter" class="org.apache.servicemix.demo.myFileFilter"> <constructor-arg value="joefred.xml" /> </bean> ... </beans>
filter
element to the endpoint's configuration. The filter
element simply wraps the bean
element that configures the file filter.
Chapter 11. Using Sender Endpoints
Abstract
11.1. Introduction to sender endpoints
Overview
Where does a sender endpoint fit into a solution?
Figure 11.1. Sender endpoint
Configuration element
sender
element. All its configuration can be specified using attributes of this element.
bean
elements or child elements of the sender
element.
11.2. Basic configuration
Overview
- the endpoint's name
- the endpoint's service name
- the file or directory to which files are written
sender
element.
Identifying the endpoint
- a service name
- an endpoint name
Table 11.1. Attributes for identifying a sender endpoint
Specifying the file destination
sender
element's directory
attribute. This attribute takes a URI that identifies a location on the file system.
Example
Example 11.1. Simple sender endpoint
<beans xmlns:file="http://servicemix.apache.org/file/1.0" xmlns:foo="http://servicemix.org/demo/"> <file:sender service="foo:fileSender" endpoint="sender" directory="outbox" /> ... </beans>
11.3. Configuring a sender endpoint's interaction with the file system
Overview
- if the endpoint creates the directory where it writes files
- how the endpoint names temporary files
Directory creation
autoCreateDirectory
attribute to false
. If the directory does not exist, the endpoint will do nothing. You will then have to create the directory manually.
Example 11.2. Sender endpoint that creates its target directory
<beans xmlns:file="http://servicemix.apache.org/file/1.0"
xmlns:foo="http://servicemix.org/demo/">
<file:sender service="foo:fileSender"
endpoint="fileSender"
directory="outbox"
autoCreateDirectory="false" />
...
</beans>
Appending data
append
attribute to true.
Example 11.3. Sender endpoint that appends existing files
<beans xmlns:file="http://servicemix.apache.org/file/1.0"
xmlns:foo="http://servicemix.org/demo/">
<file:sender service="foo:fileSender"
endpoint="fileSender"
directory="outbox"
append="true" />
...
</beans>
Temporary file naming
Table 11.2. Attributes used to determine a temporary file name
tempFilePrefixXXXXXtempFileSuffix
. The five Xs in the middle of the filename will be filled with randomly generated characters. So given the configuration shown in Example 11.4, “Configuring a sender endpoint's temporary file prefix”, a possible temporary filename would be widgets-xy60s.xml
.
Example 11.4. Configuring a sender endpoint's temporary file prefix
<beans xmlns:file="http://servicemix.apache.org/file/1.0"
xmlns:foo="http://servicemix.org/demo/">
<file:sender service="foo:fileSender"
endpoint="fileSender"
directory="outbox"
tempFilePrefix="widgets-" />
...
</beans>
Chapter 12. File Marshalers
Abstract
Overview
org.apache.servicemix.components.util.FileMarshaler
interface. You can easily configure your endpoints to use your custom marshaler instead of the default one.
Provided file marshalers
- Binary File Marshaler
- The binary file marshaler is provided by the class
org.apache.servicemix.components.util.BinaryFileMarshaler
. It reads in binary data and adds the data to the normalized message as an attachment. You can set the name of the attachment and specify a content type for the attachment using the properties shown in Table 12.1, “Properties for configuring the binary file marshaler”.Table 12.1. Properties for configuring the binary file marshaler
Name Description Default attachment Specifies the name of the attachment added to the normalized message. content
contentType Specifies the content type of the binary data being used. Content types are specified using MIME types. MIME types are specified by RFC 2045. - Flat File Marshaler
- The flat file marshaler is provided by the class
org.apache.servicemix.components.util.SimpleFlatFileMarshaler
. It reads in flat text files and converts them into XML messages.By default, the file is wrapped in aFile
element. Each line in the file is wrapped in aLine
element with anumber
attribute that represents the position of the line in the original file.You can control some aspects of the generated XML file using the properties described in Table 12.2, “Properties used to control the flat file marshaler”.Table 12.2. Properties used to control the flat file marshaler
Implementing a file marshaler
org.apache.servicemix.components.util.FileMarshaler
interface. Example 12.1, “The file marshaler interface” shows the interface.
Example 12.1. The file marshaler interface
package org.apache.servicemix.components.util; import java.io.IOException; import java.io.InputStream; import java.io.OutputStream; import javax.jbi.JBIException; import javax.jbi.messaging.MessageExchange; import javax.jbi.messaging.MessagingException; import javax.jbi.messaging.NormalizedMessage; public interface FileMarshaler { void readMessage(MessageExchange exchange, NormalizedMessage message, InputStream in, String path) throws IOException, JBIException; String getOutputName(MessageExchange exchange, NormalizedMessage message) throws MessagingException; void writeMessage(MessageExchange exchange, NormalizedMessage message, OutputStream out, String path) throws IOException, JBIException; }
FileMarshaler
interface has three methods that need to be implemented:
readMessage()
- The
readMessage()
method is responsible for reading a file from the file system and converting the data into a normalized message. Table 12.3, “Parameters for reading messages from the file system” describes the parameters used by the method.Table 12.3. Parameters for reading messages from the file system
Name Description exchange
Contains the MessageExchange
object that is going to be passed to the NMR.message
Contains the NormalizedMessage
object that is going to be passed to the NMR.in
Contains the BufferedInputStream
which points to the file in the file system.path
Contains the full path to the file on the file system as determined by the Java getCanonicalPath()
method. getOutputName()
- The
getOutputName()
method returns the name of the file to be written to the file system. The message exchange and the message received by the sender endpoint are passed to the method.ImportantThe returned file name does not contain a directory path. The sender endpoint uses the directory it was configured to use. writeMessage()
- The
writeMessage()
method is responsible for writing messages received from the NMR to the file system as files. Table 12.4, “Parameters for writing messages to the file system” describes the parameters used by the method.Table 12.4. Parameters for writing messages to the file system
Name Description exchange
Contains the MessageExchange
object received from the ESB.message
Contains the NormalizedMessage
object received from the ESB.out
Contains the BufferedOutputStream
which points to the file in the file system.path
Contains the path to the file are returned from the getOutputName()
method.
Example 12.2. Simple file marshaler
package org.apache.servicemix.demos; import java.io.File; import java.io.IOException; import java.io.InputStream; import java.io.ObjectOutputStream; import java.io.OutputStream; import javax.jbi.JBIException; import javax.jbi.messaging.MessageExchange; import javax.jbi.messaging.MessagingException; import javax.jbi.messaging.NormalizedMessage; public class myFileMarshaler implements FileMarshaler { public void readMessage(MessageExchange exchange, NormalizedMessage message, InputStream in, String path) throws IOException, JBIException { message.setContent(new StreamSource(in, path)); } public String getOutputName(MessageExchange exchange, NormalizedMessage message) throws MessagingException { return "fred.xml"; } public void writeMessage(MessageExchange exchange, NormalizedMessage message, OutputStream out, String path) throws IOException, JBIException { Source src = message.getContent(); if (src == null) { throw new NoMessageContentAvailableException(exchange); } try { ObjectOutputStream objectOut = new ObjectOutputStream(out); objectOut.writeObject(src); } } }
Configuring an endpoint to use a file marshaler
marshaler
attribute. The marshaler
attribute's value is a reference to a bean
element specifying the class of the file filter implementation.
Example 12.3. Poller endpoint using a file marshaler
<beans xmlns:file="http://servicemix.apache.org/file/1.0" xmlns:foo="http://servicemix.org/demo/"> <file:poller service="foo:filePoller" endpoint="filePoller" targetService="foo:fileSender" file="inbox" marshaler="#myMarshaler" /> <bean id="myMarshaler" class="org.apache.servicemix.demo.myFileMarshaler" />
marshaler
element to the endpoint's configuration. The marshaler
element simply wraps the bean
element that configures the file marshaler.
Appendix B. Poller Endpoint Properties
Attributes
Table B.1. Attributes for configuring a poller endpoint
Name | Type | Description | Default |
---|---|---|---|
service | QName | Specifies the service name of the endpoint. | required |
endpoint | String | Specifies the name of the endpoint. | required |
interfaceName | QName | Specifies the interface name of the endpoint. | |
targetService | QName | Specifies the service name of the target endpoint. | |
targetEndPoint | String | Specifies the name of the target endpoint. | |
targetInterface | QName | Specifies the interface name of the target endpoint. | |
targetUri | string | Specifies the URI of the target endpoint. | |
autoCreateDirectory | boolean | Specifies if the endpoint will create the target directory if it does not exist. | true |
firstTime | date | Specifies the date and the time the first poll will take place. | null (The first poll will happen right after start up.) |
delay | long | Specifies amount of time, in milliseconds, to wait before performing the first poll. | 0 |
period | long | Specifies the amount of time, in milliseconds, between polls. | 5000 |
file | String | Speficies the file or directory to poll. | required |
deleteFile | boolean | Specifies if the file is deleted after it is processed. | true |
recursive | boolean | Specifies if the endpoint processes sub directories when polling. | true |
archive | string | Specifies the name of the directory to archive files into before deleting them. | null (no archiving) |
Beans
Table B.2. Beans for configuring a poller endpoint
Name | Type | Description | Default |
---|---|---|---|
marshaler | org.apache.servicemix.components.util.FileMarshaler | Specifies the class used to marshal data from the file. | DefaultFileMarshaler |
lockManager | org.apache.servicemix.locks.LockManager | Specifies the class implementing the file locking. | SimpleLockManager |
filter | java.io.FileFilter | Specifies the class implementing the filtering logic to use for selecting files. |
Appendix C. Sender Endpoint Properties
Attributes
Table C.1. Attributes for configuring a sender endpoint
Name | Type | Description | Default |
---|---|---|---|
service | QName | Specifies the service name of the endpoint. | required |
endpoint | String | Specifies the name of the endpoint. | required |
directory | String | Specifies the name of the directory into which data is written. | required |
autoCreateDirectory | boolean | Specifies if the endpoint creates the output directory if it does not exist. | true |
append | boolean | Specifies if the data is appended to the end of an existing file or if the data is written to a new file. | false |
tempFilePrefix | String | Specifies the prefix used when creating output files. | servicemix- |
tempFileSuffix | String | Specifies the file extension to use when creating output files. | .xml |
Beans
Table C.2. Attributes for configuring a sender endpoint
Name | Type | Description | Default |
---|---|---|---|
marshaler | org.apache.servicemix.components.util.FileMarshaler | Specifies the marshaler to use when writing data from the NMR to the file system. | DefaultFileMarshaler |
Part III. JMS Binding Component
Abstract
Chapter 13. Introduction to the Red Hat JBoss Fuse JMS Binding Component
Abstract
Overview
- Consumer Endpoints
- A Consumer endpoint's primary roll is to listen for messages on an external JMS destination and pass them into to the NMR for delivery to endpoints inside of the Red Hat JBoss Fuse container. Consumer endpoints can send responses if one is required.
- Provider Endpoints
- A Provider endpoint's primary roll is to take messages from the NMR and send them to an external JMS destination.
xbean.xml
file. There are some instances where you will need to develop your own Java classes to supplement the basic functionality provided by the binding components default implementations. These cases are discussed at the end of this guide.
Key features
- Support for JMS 1.0.2 and JMS 1.1
- JMS transactions
- XA transactions
- Support of all MEP patterns
- SOAP support
- MIME support
- Customizable message marshaling
Contents of a JMS service unit
xbean.xml
- The
xbean.xml
file contains the XML configuration for the endpoint defined by the service unit. The contents of this file are the focus of this guide.NoteThe service unit can define more than one endpoint. meta-inf/jbi.xml
- The
jbi.xml
file is the JBI descriptor for the service unit. Example 13.1, “JBI Descriptor for a JMS Service Unit” shows a JBI descriptor for a JMS service unit.Example 13.1. JBI Descriptor for a JMS Service Unit
The elements shown in Example 13.1, “JBI Descriptor for a JMS Service Unit” do the following:- 1
- The
service
element is the root element of all service unit descriptors. The value of thebinding-component
attribute is alwaysfalse
. - 2
- The
service
element contains namespace references for all of the namespaces defined in thexbean.xml
file'sbean
element. - 3
- The
provides
element corresponds to a JMS provider endpoint. Theservice-name
attribute derives its value from theservice
attribute in the JMS provider's configuration.NoteThis attribute can also appear on aconsumes
element. - 4
- The
endpoint-name
attribute derives its value from theendpoint
attribute in the JMS provider's configuration.NoteThis attribute can also appear on aconsumes
element. - 5
- The
consumes
element corresponds to a JMS consumer endpoint. Theinterface-name
attribute derives its value from theinterfaceName
attribute in the JMS consumer's configuration.NoteThis attribute can also appear on aprovides
element.
Using the Maven JBI tooling
- servicemix-jms-consumer-endpoint
- The servicemix-jms-consumer-endpoint archetype creates a project that results in a service unit that configures a JMS consumer endpoint.TipYou can use the smx-arch command to in place of typing the entire Maven command.
smx-arch su jms-consumer ["-DgroupId=my.group.id"] ["-DartifactId=my.artifact.id"]
- servicemix-jms-provider-endpoint
- The servicemix-jms-provider-endpoint archetype creates a project that results in a service unit that configures a JMS provider endpoint.TipYou can use the smx-arch command to in place of typing the entire Maven command.
smx-arch su jms-provider ["-DgroupId=my.group.id"] ["-DartifactId=my.artifact.id"]
- a
pom.xml
file containing the metadata needed to generate and package the service unit - a
src/main/resources/xbean.xml
file containing the configuration for the endpointImportantThe endpoint configuration generated by the archetype is for the deprecated JMS endpoints. While this configuration will work, it is not recommended for new projects and is not covered in this guide.
java
folder to the generated src
folder. You also need to modify the generated pom.xml
file to compile the code and package it with the service unit.
OSGi Packaging
- include an OSGi bundle manifest in the
META-INF
folder of the bundle - add the following to your service unit's configuration file:
<bean class="org.apache.servicemix.common.osgi.EndpointExporter" />
Namespace
http://servicemix.apache.org/jms/1.0
namespace. You will need to add a namespace declaration similar to the one in Example 13.2, “Namespace Declaration for Using JMS Endpoints” to your xbeans.xml
file's beans
element.
Example 13.2. Namespace Declaration for Using JMS Endpoints
<beans ...
xmlns:jms="http://servicemix.apache.org/jms/1.0"
... >
...
</beans>
beans
element's xsi:schemaLocation
as shown in Example 13.3, “Schema Location for Using JMS Endpoints”.
Example 13.3. Schema Location for Using JMS Endpoints
<beans ... xsi:schemaLocation="... http://servicemix.apache.org/jms/1.0 http://servicemix.apache.org/jms/1.0/servicemix-jms.xsd ..."> ... </beans>
Chapter 14. Configuring the Connection Factory
Abstract
ConnectionFactory
object to create connections to the broker. The ConnectionFactory
object is a JMS object that is provided along with the JMS broker. Each JMS provider has a unique ConnectionFactory
object that uses properties specific to a particular JMS implementation.
ConnectionFactory
object. Often the ConnectionFactory
object is looked up through JNDI. However, the information needed depends on the JMS provider you are using.
ConnectionFactory
objects for each of these platforms.
14.1. Using Apache ActiveMQ Connection Factories
Overview
InstallDir\lib
folder.
Namespace
beans
element:
xmlns:amqpool="http://jencks.org/amqpool/2.0"
Simple pool
amqpool:pool
element. The attributes used to configure the simple pooled connection factory are described in Table 14.1, “Attributes for Configuring the Simple AMQPool Connection Factory”.
Table 14.1. Attributes for Configuring the Simple AMQPool Connection Factory
Example 14.1. Configuring a Simple AMQPool Connection Factory
<beans xmlns:amqpool="http://jencks.org/amqpool/2.0" ... > ... <amqpool:pool id="connectionFactory" url="tcp://localhost:61616" maxConnections="8" /> </beans>
XA pool
amqpool:xa-pool
element. The attributes used to configure the XA pooled connection factory are described in Table 14.2, “Attributes for Configuring the XA AMQPool Connection Factory”.
Table 14.2. Attributes for Configuring the XA AMQPool Connection Factory
Example 14.2. Configuring an XA AMQPool Connection Factory
<beans xmlns:amqpool="http://jencks.org/amqpool/2.0" xmlns:jencks="http://jencks.org/2.0" ... > ... <amqpool:xa-pool id="connectionFactory" url="tcp://localhost:61616" maxConnections="8" transactionManager="#transactionManager" /> <jencks:transactionManager id="transactionManager" transactionLogDir="./data/txlog" defaultTransactionTimeoutSeconds="600" /> </beans>
JCA pool
amqpool:jca-pool
element. The attributes used to configure the JCA pooled connection factory are described in Table 14.3, “Attributes for Configuring the JCA AMQPool Connection Factory”.
Table 14.3. Attributes for Configuring the JCA AMQPool Connection Factory
Example 14.3. Configuring a JCA AMQPool Connection Factory
<beans xmlns:amqpool="http://jencks.org/amqpool/2.0" xmlns:jencks="http://jencks.org/2.0" ... > ... <amqpool:jca-pool id="connectionFactory" url="tcp://localhost:61616" maxConnections="8" transactionManager="#transactionManager" name="joeFred" /> <jencks:transactionManager id="transactionManager" transactionLogDir="./data/txlog" defaultTransactionTimeoutSeconds="600" /> </beans>
14.2. Using JNDI
Overview
Spring JEE JNDI lookup
- Add the following namespace declaration to your
beans
element in your service unit's configuration.xmlns:jee="http://www.springframework.org/schema/jee"
- Add a
jee:jndi-lookup
element to your service unit's configuration.Thejee:jndi-lookup
element has two attributes. They are described in Table 14.4, “Attributes for Using Spring's JEE JNDI Lookup”. - Add a
jee:environment
child element to thejee:jndi-lookup
element.Thejee:environment
element contains a collection of Java properties that are used to access the JNDI provider. These properties will be provided by your JNDI provider's documentation.
Example 14.4. Getting the WebLogic Connection Factory Using Spring's JEE JNDI Look-up
<beans xmlns:jee="http://www.springframework.org/schema/jee" ... > ... <jee:jndi-lookup id="connectionFactory" jndi-name="weblogic.jms.XAConnectionFactory"> <jee:environment> java.naming.factory.initial=weblogic.jndi.WLInitialContextFactory java.naming.provider.url=t3://localhost:7001 </jee:environment> </jee:jndi-lookup> ... </beans>
Spring JNDI Templates
JndiTemplate
bean. Using this approach, you configure an instance of the JndiTemple
bean and then use the bean to perform all of your JNDI look-ups using a JndiObjectFactoryBean
bean.
- Add a
bean
element to your configuration for the JNDI template.- Set the
bean
element'sid
attribute to a unique identifier. - Set the
bean
element'sclass
attribute toorg.springframework.jndi.JndiTemplate
. - Add a
property
child element to thebean
element.Theproperty
element will contain the properties for accessing the JNDI provider. - Set the
property
element'sname
attribute toenvironment
. - Add a
props
child to theproperty
element. - Add a
prop
child element to theprops
element for each Java property needed to connect to the JNDI provider.Aprop
element has a single attribute calledkey
whose value is the name of the Java property being set. The value of the element is the value of the Java property being set. Example 14.5, “Setting a Java Property” shows aprop
element for setting the java.naming.factory.initial property.Example 14.5. Setting a Java Property
<prop key="java.naming.factory.initial"> com.sun.jndi.fscontext.RefFSContextFactory </prop>
NoteThe properties you need to set will be determined by your JNDI provider. Check its documentation.
- Add a
bean
element to your configuration to retrieve the JMS connection factory using the JNDI template.- Set the
bean
element'sid
attribute to a unique identifier. - Set the
bean
element'sclass
attribute toorg.springframework.jndi.JndiObjectFactoryBean
. - Add a
property
child element to thebean
element.Thisproperty
element loads the JNDI template to be used for the look-up. You must set itsname
attribute tojndiTemplate
. The value of itsref
attribute is taken from thename
attribute of thebean
element that configured the JNDI template. - Add a second
property
child element to thebean
element.Thisproperty
element specifies the JNDI name of the connection factory. You must set itsname
attribute tojndiTemplate
. - Add a
value
child element to theproperty
element.The value of the element is the JNDI name of the connection factory.
Example 14.6. Using a JNDI Template to Look Up a Connection Factory
<beans ... > ... <bean id="jndiTemplate" class="org.springframework.jndi.JndiTemplate"> <property name="environment"> <props> <prop key="java.naming.factory.initial"> com.sun.jndi.fscontext.RefFSContextFactory </prop> <prop key="java.naming.provider.url"> file:/tmp/ </prop> </props> </property> </bean> <bean id="connectionFactory" class="org.springframework.jndi.JndiObjectFactoryBean"> <property name="jndiTemplate" ref="jndiTemplate" /> <property name="jndiName"> <value>MQConnFactory</value> </property> </bean> ... </beans>
14.3. Using a Spring Bean
Overview
ConnectionFactory
for your JMS provider.
Example
Example 14.7. Configuring a Connection Factory with a Spring Bean
<bean id="connectionFactory" class="com.ibm.mq.jms.MQQueueConnectionFactory"> <property name="transportType"> <util:constant static-field="com.ibm.mq.jms.JMSC.MQJMS_TP_CLIENT_MQ_TCPIP" /> </property> <property name="queueManager" value="my.queue.mgr" /> <property name="hostName" value="myHost" /> <property name="channel" value="myChannel" /> <property name="port" value="12345" /> </bean>
Chapter 15. Creating a Consumer Endpoint
Abstract
MessageListener
interface.
15.1. Introduction to Consumer Endpoints
Where does a consumer fit into a solution?
Figure 15.1. Consumer Endpoint
Types of consumer endpoints
- Generic
- The generic consumer endpoint can handle any type of message data. It is configured using the
jms:consumer
element. - SOAP
- The SOAP consumer endpoint is specifically tailored to receive SOAP messages. It uses a WSDL document to define the structure of the messages. It is configured using the
jms:soap-consumer
element.TipThe Apache CXF binding component's JMS transport is better adapted to handling SOAP messages, but offers less control over the JMS connection. - JCA
- The JCA consumer endpoint uses JCA to connect to the JMS provider. It is configured using the
jms:jca-consumer
element. For more information on using the JCA consumer endpoint, see Section 15.3, “Using the JCA Consumer Endpoint”.
15.2. Using the Generic Endpoint or the SOAP Endpoint
15.2.1. Basic Configuration
Procedure
- Decide what type of consumer endpoint to use.
- Specify the name of the service for which this endpoint is acting as a proxy.This is specified using the
service
attribute.TipIf you are using a SOAP consumer and your WSDL file only has one service defined, you do not need to specify the service name. - Specify the name of the endpoint for which this endpoint is acting as a proxy.This is specified using the
endpoint
attribute.TipIf you are using a SOAP consumer and your WSDL file only has one endpoint defined, you do not need to specify the endpoint name. - Specify the connection factory the endpoint will use.The endpoint's connection factory is configured using the endpoint's
connectionFactory
attribute. TheconnectionFactory
attribute's value is a reference to the bean that configures the connection factory. For example, if the connection factory configuration bean is namedwidgetConnectionFactory
, the value of theconnectionFactory
attribute would be#widgetConnectionFactory
.For information on configuring a connection factory see Chapter 14, Configuring the Connection Factory. - Specify the destination onto which the endpoint will place messages.For more information see the section called “Configuring a destination”.
- Specify the ESB endpoint to which incoming messages are targeted.For more information see the section called “Specifying the target endpoint”.
- If you are using a JMS SOAP consumer, specify the location of the WSDL defining the message exchange using the
wsdl
attribute. - If your JMS destination is a topic, set the
pubSubDomaim
attribute totrue
. - If your endpoint is interacting with a broker that only supports JMS 1.0.2, set the
jms102
attribute totrue
.
Configuring a destination
- The endpoint will check to see if you configured the destination explicitly.You configure a destination using a Spring bean. You can add the bean directly to the endpoint by wrapping it in a
jms:destination
child element. You can also configure the bean separately and refer the bean using the endpoint'sdestination
attribute as shown in Example 15.1, “Configuring a Consumer's Destination”.Example 15.1. Configuring a Consumer's Destination
<beans xmlns:jms="http://servicemix.apache.org/jms/1.0" ... > ... <jms:consumer service="my:widgetService" endpoint="jbiWidget" destination="#widgetQueue" ... /> ... <jee:jndi-lookup id="widgetQueue" jndi-name="my.widget.queue"> <jee:environment> java.naming.factory.initial=weblogic.jndi.WLInitialContextFactory java.naming.provider.url=t3://localhost:7001 </jee:environment> </jee:jndi-lookup> ... </beans>
- If you did not explicitly configure a destination, the endpoint will use the value of the
destinationName
attribute to choose its destination.The value of thedestinationName
attribute is a string that will be used as the name for the JMS destination. The binding component's default behavior when you provide a destination name is to resolve the destination using the standard JMSSession.createTopic()
andSession.createQueue()
methods.NoteYou can override the binding component's default behavior by providing a customDestinationResolver
implementation. See Section 19.2, “Using a Custom Destination Resolver”.
Specifying the target endpoint
- If you explicitly specify an endpoint using both the
targetService
attribute and thetargetEndpoint
attribute, the ESB will use that endpoint.ThetargetService
attribute specifies the QName of a service deployed into the ESB. ThetargetEndpoint
attribute specifies the name of an endpoint deployed by the service specified by thetargetService
attribute. - If you only specify a value for the
targetService
attribute, the ESB will attempt to find an appropriate endpoint on the specified service. - If you do not specify a service name or an endpoint name, you must specify an the name of an interface that can accept the message using the
targetInterface
attribute. The ESB will attempt to locate an endpoint that implements the specified interface and direct the messages to it.Interface names are specified as QNames. They correspond to the value of thename
attribute of either a WSDL 1.1serviceType
element or a WSDL 2.0interface
element.
Examples
Example 15.2. Basic Configuration for a Generic Consumer Endpoint
<beans xmlns:jms="http://servicemix.apache.org/jms/1.0" ... > ... <jms:consumer service="my:widgetService" endpoint="jbiWidget" destinationName="widgetQueue" connectionFactory="#connectionFactory" targetService="my:targetService" /> ... </beans>
Example 15.3. Basic Configuration for a SOAP Consumer Endpoint
<beans xmlns:jms="http://servicemix.apache.org/jms/1.0" ... > ... <jms:soap-consumer wsdl="classpath:widgets.wsdl" destinationName="widgetQueue" connectionFactory="#connectionFactory" targetService="my:targetService" /> ... </beans>
15.2.2. Listener Containers
Overview
Types of listener containers
- Simple
- The simple listener container creates a fixed number of JMS sessions at startup and uses them throughout the lifespan of the container. It cannot dynamically adapt to runtime conditions nor participate in externally managed transactions.
- Default
- The default listener container provides the best balance between placing requirements on the JMS provider and features. Because of this, it is the default listerner container for Red Hat JBoss Fuse JMS consumer endpoints. The default listener container can adapt to changing runtime demands. It is also capable of participating in externally managed transactions.
- Server session
- The server session listener container leverages the JMS
ServerSessionPool
SPI to allow for dynamic management of JMS sessions. It provides the best runtime scaling and supports externally managed transactions. However, it requires that your JMS provider supports the JMSServerSessionPool
SPI.
Specifying an endpoint's listener container
listenerType
attribute. Table 15.1, “Values for Configuring a Consumer's Listener Container” lists the values for the listenerType
attribute.
Table 15.1. Values for Configuring a Consumer's Listener Container
Example 15.4. Configuring a SOAP Consumer to Use the Simple Listener Container
<beans xmlns:jms="http://servicemix.apache.org/jms/1.0"
... >
...
<jms:soap-consumer wsdl="classpath:widgets.wsdl"
destinationName="widgetQueue"
connectionFactory="#connectionFactory"
listenerType="simple" />
...
</beans>
Performace tuning using the listener container
Table 15.2. Attributes Used to Performance Tune Standard JMS Consumers and SOAP JMS Consumers
Example 15.5. Tuning a Generic Consumer Endpoint
<beans xmlns:jms="http://servicemix.apache.org/jms/1.0" ... > ... <jms:consumer service="my:widgetService" endpoint="jbiWidget" destinationName="widgetQueue" connectionFactory="#connectionFactory" cacheLevel="3" maxMessagesPerTask="1"/> ... </beans>
Configuring the server session listener container's session factory
ServerSessionPool
SPI to tune an endpoint's performance. In order for the listener container to function,k it uses a ServerSessionFactory
object. By default, the Red Hat JBoss Fuse JMS BC uses the Spring framework's SimpleServerSessionFactory
object. This server session factory creates a new JMS ServerSession
object with a new JMS session everytime it is called.
serverSessionFactory
attribute. This attribute provides a reference to the bean configuring the ServerSessionFactory
object.
ServerSessionFactory
object by adding a serverSessionFactory
child element to the endpoint's configuration. This element would wrap the ServerSessionFactory
object's configuration bean.
CommonsPoolServerSessionFactory
object as a session factory.
Example 15.6. Configuring a Consumer to Use a Pooled Session Factory
<beans xmlns:jms="http://servicemix.apache.org/jms/1.0" ... > ... <jms:consumer service="my:widgetService" endpoint="jbiWidget" destinationName="widgetQueue" connectionFactory="#connectionFactory" listenerType="server" serverSessionFactory="#pooledSessionFactory"/> <bean id="pooledSessionFactory" class="org.springframework.jms.listener.serversession.CommonsPoolServerSessionFactory" /> ... </beans>
15.2.3. Advanced Configuration
Using transactions
transacted
attribute to specify the type of transactions to use. Table 15.3, “Consumer Transaction Support” describes the possible values for the transacted
attribute.
Table 15.3. Consumer Transaction Support
Value | Description |
---|---|
none | Specifies that message exchanges are not wrapped in a transaction. This is the default setting. |
jms | Specifies that message exchanges are wrapped in local JMS transactions. |
xa | Specifies that message exchanges will be wrapped in an externally managed XA transaction. You must also provide a transaction manager when using XA transactions. |
Using message selectors
messageSelector
attribute. The value of the attribute is the string value of the selector. For more information on the syntax used to specify message selectors, see the JMS 1.1 specification.
Using durable subscriptions
subscriptionDurable
attribute to true
. You specify the name used to register the durable subscription using the durableSubscriberName
attribute.
Example 15.7. Consumer using a Durable Subscription
<beans xmlns:jms="http://servicemix.apache.org/jms/1.0" ... > ... <jms:soap-consumer wsdl="classpath:widgets.wsdl" destinationName="widgetQueue" connectionFactory="#connectionFactory" subscriptionDurable="true" durableSubscriberName="widgetSubscriber" /> ... </beans>
15.2.4. SOAP Specific Configuration
Overview
Using the JBI wrapper
useJbiWrapper
attribute to true
.
Example 15.8. Configuring a SOAP Consumer to Use the JBI Wrapper
<beans xmlns:jms="http://servicemix.apache.org/jms/1.0"
... >
...
<jms:soap-consumer wsdl="classpath:widgets.wsdl"
destinationName="widgetQueue"
connectionFactory="#connectionFactory"
useJbiWrapper="true" />
...
</beans>
WSDL verification
validateWsdl
attribute to false
.
15.3. Using the JCA Consumer Endpoint
Procedure
- Specify the name of the service for which this endpoint is acting as a proxy.This is specified using the
service
attribute. - Specify the name of the endpoint for which this endpoint is acting as a proxy.This is specified using the
endpoint
attribute. - Specify the connection factory the endpoint will use.The endpoint's connection factory is configured using the endpoint's
connectionFactory
attribute. TheconnectionFactory
attribute's value is a reference to the bean that configures the connection factory. For example if the connection factory configuration bean is namedwidgetConnectionFactory
, the value of theconnectionFactory
attribute would be#widgetConnectionFactory
.For information on configuring a connection factory see Chapter 14, Configuring the Connection Factory. - Specify the destination onto which the endpoint will place messages.For more information see the section called “Configuring a destination”.
- Configure the JCA resource adapter that the consumer will use.You configure the endpoint's resource adapter using the
resourceAdapter
attribute. The attribute's value is a reference to the bean that configures the resource adapter. - Configure the
ActivationSpec
object that will be used by the endpoint.You configure the endpoint's resource adapter using theactivationSpec
attribute. The attribute's value is a reference to the bean that configures theActivationSpec
object. - Specify the ESB endpoint to which incoming messages are targeted.For more information see the section called “Specifying the target endpoint”.
- If your JMS destination is a topic, set the
pubSubDomaim
attribute totrue
.
Configuring a destination
- The endpoint will check to see if you configured the destination explicitly.You configure a destination using a Spring bean. You can add the bean directly to the endpoint by wrapping it in a
jms:destination
child element. You can also configure the bean separately and refer the bean using the endpoint'sdestination
attribute as shown in Example 15.9, “Configuring a JCA Consumer's Destination”.Example 15.9. Configuring a JCA Consumer's Destination
<beans xmlns:jms="http://servicemix.apache.org/jms/1.0" ... > ... <jms:jca-consumer service="my:widgetService" endpoint="jbiWidget" destination="#widgetQueue" ... /> ... <jee:jndi-lookup id="widgetQueue" jndi-name="my.widget.queue"> <jee:environment> java.naming.factory.initial=weblogic.jndi.WLInitialContextFactory java.naming.provider.url=t3://localhost:7001 </jee:environment> </jee:jndi-lookup> ... </beans>
- If you did not explicitly configure a destination, the endpoint will use the value of the
destinationName
attribute to choose its destination.The value of thedestinationName
attribute is a string that corresponds to the name of the JMS destination. The binding component's default behavior when you provide a destination name is to resolve the destination using the standard JMSSession.createTopic()
andSession.createQueue()
methods.NoteYou can override the binding component's default behavior by providing a customDestinationResolver
implementation. See Section 19.2, “Using a Custom Destination Resolver”.
Specifying the target endpoint
- If you explicitly specify an endpoint using both the
targetService
attribute and thetargetEndpoint
attribute, the ESB will use that endpoint.ThetargetService
attribute specifies the QName of a service deployed into the ESB. ThetargetEndpoint
attribute specifies the name of an endpoint deployed by the service specified by thetargetService
attribute. - If you only specify a value for the
targetService
attribute, the ESB will attempt to find an appropriate endpoint on the specified service. - If you do not specify a service name or an endpoint name, you must specify an the name of an interface that can accept the message using the
targetInterface
attribute. The ESB will attempt to locate an endpoint that implements the specified interface and direct the messages to it.Interface names are specified as QNames. They correspond to the value of thename
attribute of either a WSDL 1.1serviceType
element or a WSDL 2.0interface
element.
Example
Example 15.10. Basic Configuration for a JCA Consumer Endpoint
<beans xmlns:jms="http://servicemix.apache.org/jms/1.0" ... > ... <jms:jca-consumer service="my:widgetService" endpoint="jbi" destinationName="widgetQueue" connectionFactory="#connectionFactory" resourceAdapter="#ra" activationSpec="#as" targetService="my:targetService" /> <bean id="ra" class="org.activemq.ra.ActiveMQConnectionFactory"> ... </bean> <bean id="as" class="org.apache.activemq.ra.ActiveMQActivationSpec"> ... </bean> ... </beans>
15.4. Configuring How Replies are Sent
- the reply message's priority
- the reply message's persistence
- the reply message's lifespan
15.4.1. Configuring the Reply Destination
Overview
Determining the reply destination
- If the in message of the exchange includes a value for the JMSReplyTo property, that value is used as the reply destination.
- If the JMSReplyTo is not specified, the endpoint looks for a destination chooser implementation to use.If you have configured your endpoint with a destination chooser, the endpoint will use the destination chooser to select the reply destination.For more information on using destination choosers see Section 19.1, “Using a Custom Destination Chooser”.
- If the JMSReplyTo is not specified and there is no configured destination chooser, the endpoint checks its
replyDestination
attribute for a destination.You configure a destination using a Spring bean. The recommend method to configure the destination is to configure the bean separately and refer the bean using the endpoint'sreplyDestination
attribute as shown in Example 15.11, “Configuring a Consumer's Reply Destination”. You can also add the bean directly to the endpoint by wrapping it in ajms:replyDestination
child element. - As a last resort, the endpoint will use the value of the
replyDestinationName
attribute to determine the reply destination.ThereplyDestinationName
attribute takes a string that is used as the name of the destination to use. The binding component's default behavior when you provide a destination name is to resolve the destination using the standard JMSSession.createTopic()
andSession.createTopic()
methods to resolve the JMS destination.NoteYou can override the binding component's default behavior by providing a customDestinationResolver
implementation. See Section 19.2, “Using a Custom Destination Resolver”.
Example
Example 15.11. Configuring a Consumer's Reply Destination
<beans xmlns:jms="http://servicemix.apache.org/jms/1.0" ... > ... <jms:consumer service="my:widgetService" endpoint="jbiWidget" destinationName="my.widgetQueue" connectionFactory="#connectionFactory" replyDestination="#widgetReplyQueue" /> ... <jee:jndi-lookup id="widgetReplyQueue" jndi-name="my.widget.reply.queue"> <jee:environment> java.naming.factory.initial=weblogic.jndi.WLInitialContextFactory java.naming.provider.url=t3://localhost:7001 </jee:environment> </jee:jndi-lookup> ... </beans>
15.4.2. Configuring the Qualities of Service
Overview
- the reply message's priority
- the reply message's persistence
- the reply message's lifespan
Setting the reply message's priority
replyPriority
attribute. The value is used to set the reply message's JMSPriority property.
Setting the reply message's persistence
replyDeliveryMode
attribute. The value you provide for the replyDeliveryMode
attribute is used to set the reply message's JMSDeliveryMode property.
deliveryMode
attribute to 2
. This setting corresponds to DeliveryMode.PERSISTENT
.
deliveryMode
attribute to 1
. This setting corresponds to DeliveryMode.NON_PERSISTENT
.
Setting a reply message's lifespan
replyTimeToLive
attribute. The value is the number of milliseconds you want the message to be available from the time it is sent.
replyTimeToLive
attribute is used to compute the value for the reply message's JMSExpirary property. The value is computed by adding the specified number of milliseconds to the time the message is created.
Enforcing the configured values
replyExplicitQosEnabled
to true
. Doing so instructs the consumer to always use the values provided in the configuration.
Example
Example 15.12. Consumer with Reply QoS Properties
<beans xmlns:jms="http://servicemix.apache.org/jms/1.0" ... > ... <jms:jca-consumer service="my:widgetService" endpoint="jbiWidget" connectionFactory="#connectionFactory" destinationName="widgetQueue" resourceAdapter="#ra" activationSpec="#as" replyExplicitQosEnabled="true" replyDeliveryMode="1" replyPriority="0" /> ... </beans>
15.4.3. Setting Custom JMS Properties
Overview
map
element. You can configure one static map that will be applied to every reply message generated by the consumer.
Setting custom JMS header properties
Defining the property map
java.util.Map
object. You define that map object using the Spring util:map
element.
util:map
element is defined in the http://www.springframework.org/schema/util
namespace. In order to use the element you will need to add the following namespace alias to your beans
element:
xmlns:util="http://www.springframework.org/schema/util"
entry
child element's to the util:map
element. Each entry
element takes two attributes. The key
entry is the map key and corresponds to the properties name. The value
attribute is the value of the property.
entry
element's ref
attribute instead of the value
attribute. The ref
attribute points to another bean
element that defines a Java object.
Example
Example 15.13. Adding Custom Properties to a Reply Message
<beans xmlns:jms="http://servicemix.apache.org/jms/1.0" xmlns:util="http://www.springframework.org/schema/util" ... > ... <jms:consumer service="my:widgetService" endpoint="jbiWidget" destinationName="my.widgetQueue" connectionFactory="#connectionFactory" replyDestination="#widgetReplyQueue" replyProperties="#jmsProps" /> ... <util:map id="jmsProps"> <entry key="location" value="San Jose"/> <entry key="orig_code" value="sjwf"/> <entry key="client_code" value="widget010"/> </util:map> ... </beans>
Chapter 16. Creating a Provider Endpoint
Abstract
JMSTemplate
interface.
16.1. Introduction to Provider Endpoints
Where does a provider fit into a solution?
Figure 16.1. Provider Endpoint
Types of providers
- Generic
- The generic provider endpoint can handle any type of message data. It is configured using the
jms:provider
element. - SOAP
- The SOAP provider endpoint is specifically tailored to receive SOAP messages. It uses a WSDL document to define the structure of the messages. It is configured using the
jms:soap-provider
element.TipThe Apache CXF binding component's JMS transport is better adapted to handling SOAP messages, but offers less control over the JMS connection.
16.2. Basic Configuration
Procedure
- Decide what type of provider endpoint to use.
- Specify the name of the service for which this endpoint is acting as a proxy.This is specified using the
service
attribute.TipIf you are using a SOAP provider and your WSDL file only has one service defined, you do not need to specify the service name. - Specify the name of the endpoint for which this endpoint is acting as a proxy.This is specified using the
endpoint
attribute.TipIf you are using a SOAP provider and your WSDL file only has one endpoint defined, you do not need to specify the endpoint name. - Specify the connection factory the endpoint will use.The endpoint's connection factory is configured using the endpoint's
connectionFactory
attribute. TheconnectionFactory
attribute's value is a reference to the bean that configures the connection factory. For example, if the connection factory configuration bean is namedwidgetConnectionFactory
, the value of theconnectionFactory
attribute would be#widgetConnectionFactory
.For information on configuring a connection factory see Chapter 14, Configuring the Connection Factory. - Specify the destination onto which the endpoint will place messages.For more information see the section called “Configuring a destination”.
- If you are using a JMS SOAP provider, specify the location of the WSDL defining the message exchange using the
wsdl
attribute. - If your JMS destination is a topic, set the
pubSubDomaim
attribute totrue
. - If your endpoint is interacting with a broker that only supports JMS 1.0.2, set the
jms102
attribute totrue
.
Configuring a destination
- If you provided a custom
DestinationChooser
implementation, the endpoint will use that to choose it's endpoint.For more information about providing customDestinationChooser
implementations see Section 19.1, “Using a Custom Destination Chooser”. - If you did not provide a custom
DestinationChooser
implementation, the endpoint will use its defaultDestinationChooser
implementation to choose an endpoint.The default destination chooser checks the message exchange received from the NMR for a DESTINATION_KEY property. If the message exchange has that property set, it returns that destination. - If the destination chooser does not return a destination, the endpoint will check to see if you configured the destination explicitly.You configure a destination using a Spring bean. The recommend way to configure the destination is to configure the bean separately and refer the bean using the endpoint's
destination
attribute as shown in Example 16.1, “Configuring a Provider's Destination”. You can also add the bean directly to the endpoint by wrapping it in ajms:destination
child element.Example 16.1. Configuring a Provider's Destination
<beans xmlns:jms="http://servicemix.apache.org/jms/1.0" ... > ... <jms:provider service="my:widgetService" endpoint="jbiWidget" destination="#widgetQueue" connectionFactory="#connectionFactory" /> ... <jee:jndi-lookup id="widgetQueue" jndi-name="my.widget.queue"> <jee:environment> java.naming.factory.initial=weblogic.jndi.WLInitialContextFactory java.naming.provider.url=t3://localhost:7001 </jee:environment> </jee:jndi-lookup> ... </beans>
- If the destination chooser does not return a destination and you did not explicitly configure a destination, the endpoint will use the value of the
destinationName
attribute to choose its destination.ThedestinationName
attribute takes a string that is used as the name of the destination to use. The binding component's default behavior when you provide a destination name is to resolve the destination using the standard JMSSession.createTopic()
andSession.createQueue()
methods to resolve the JMS destination.NoteYou can override the binding component's default behavior by providing a customDestinationResolver
implementation. See Section 19.2, “Using a Custom Destination Resolver”.
Examples
Example 16.2. Basic Configuration for a Generic Provider Endpoint
<beans xmlns:jms="http://servicemix.apache.org/jms/1.0" ... > ... <jms:provider service="my:widgetService" endpoint="jbiWidget" destinationName="widgetQueue" connectionFactory="#connectionFactory" /> ... </beans>
Example 16.3. Basic Configuration for a SOAP Provider Endpoint
<beans xmlns:jms="http://servicemix.apache.org/jms/1.0" ... > ... <jms:soap-provider wsdl="classpath:widgets.wsdl" destinationName="widgetQueue" connectionFactory="#connectionFactory" /> ... </beans>
16.3. Configuring How Responses are Received
Overview
Configuring the response destination
- If you provided a custom
DestinationChooser
implementation, the endpoint will use that to choose it's endpoint.For more information about providing customDestinationChooser
implementations see Section 19.1, “Using a Custom Destination Chooser”. - If you did not provide a custom
DestinationChooser
implementation, the endpoint will use its defaultDestinationChooser
implementation to choose an endpoint.The default destination chooser checks the message exchange received from the NMR for a DESTINATION_KEY property. If the message exchange has that property set, it returns that destination. - If the destination chooser does not return a destination, the endpoint will check to see if you configured the destination explicitly.You configure a response destination using a Spring bean. The recommend way to configure the destination is to configure the bean separately and refer the bean using the endpoint's
replyDestination
attribute as shown in Example 16.1, “Configuring a Provider's Destination”. You can also add the bean directly to the endpoint by wrapping it in ajms:replyDestination
child element. - If the destination chooser does not return a destination and you did not explicitly configure a destination, the endpoint will use the value of the
replyDestinationName
attribute to choose its destination.ThereplyDestinationName
attribute takes a string that is used as the name of the destination to use. The binding component's default behavior when you provide a destination name is to resolve the destination using the standard JMSSession.createTopic()
andSession.createTopic()
methods to resolve the JMS destination.NoteYou can override the binding component's default behavior by providing a customDestinationResolver
implementation. See Section 19.2, “Using a Custom Destination Resolver”.
Configuring the timeout interval
recieveTimeout
attribute. The recieveTimeout
attribute specifies the number of milliseconds the provider endpoint will wait for a response before timing out.
Example
Example 16.4. JMS Provider Endpoint with a Response Destination
<beans xmlns:jms="http://servicemix.apache.org/jms/1.0" ... > ... <jms:soap-provider wsdl="classpath:widgets.wsdl" destinationName="widgetQueue" connectionFactory="#connectionFactory" recieveTimeout="60000" replyDestinationName="widgetResponse" /> ... </beans>
16.4. Advanced Provider Configuration
16.4.1. JMS Message Qualities of Service
Overview
- the message's relative priority
- the message's persistence
- the message's lifespan
Setting a message's priority
priority
attribute. The value you provide for the priority
attribute is used to set the JMS message's JMSPriority property.
Setting a message's persistence
deliveryMode
attribute. The value you provide for the deliveryMode
attribute is used to set the JMS message's JMSDeliveryMode property.
deliveryMode
attribute to 2
. This setting corresponds to DeliveryMode.PERSISTENT
.
deliveryMode
attribute to 1
. This setting corresponds to DeliveryMode.NON_PERSISTENT
.
Setting a message's life span
timeToLive
attribute. The value is the number of milliseconds you want the message to be available from the time it is sent. The default behavior is to allow messages to persist forever.
timeToLive
attribute is used to compute the value for the message's JMSExpirary property. The value is computed by adding the specified number of milliseconds to the time the message is created.
Enforcing configured values
explicitQosEnabled
attribute to true
.
Example
Example 16.5. Setting JMS Provider Endpoint Message Properties
<beans xmlns:jms="http://servicemix.apache.org/jms/1.0" ... > ... <jms:soap-provider wsdl="classpath:widgets.wsdl" destinationName="widgetQueue" connectionFactory="#connectionFactory" priority="1" explicitQosEnabled="true" /> ... </beans>
16.4.2. JMS Message Optimization
Overview
Message IDs
messageIdEnabled
attribute to false
.
messageIdEnabled
attribute to false
causes the endpoint to call its message producer's setDisableMessageID()
method with a value of true
. The JMS broker is then given a hint that it does not need to generate message IDs or add them to the messages from the endpoint. The JMS broker can choose to accept the hint or ignore it.
Time stamps
messageTimeStampEnabled
attribute to false
.
messageTimeStampEnabled
attribute to false
causes the endpoint to call its message producer's setDisableMessageTimestamp()
method with a value of true
. The JMS broker is then given a hint that it does not need to generate message IDs or add them to the messages from the endpoint. The JMS broker can choose to accept the hint or ignore it.
16.4.3. SOAP Specific Configuration
Overview
Using the JBI wrapper
useJbiWrapper
attribute to true
.
Example 16.6. Configuring a SOAP Provider to Use the JBI Wrapper
<beans xmlns:jms="http://servicemix.apache.org/jms/1.0"
... >
...
<jms:soap-provider wsdl="classpath:widgets.wsdl"
destinationName="widgetQueue"
connectionFactory="#connectionFactory"
useJbiWrapper="true" />
...
</beans>
WSDL verification
validateWsdl
attribute to false
.
Chapter 17. Making Endpoints Stateful
Abstract
Overview
Activating statefullness
stateless
attribute to false
.
Configuring the datastore
storeFactory
attribute to reference a bean configuring an instance of the org.apache.servicemix.store.jdbc.JdbcStoreFactory
class. Table 17.1, “Properties Used to Configure a JDBC Store Factory” list the properties you can set for the JDBC store factory.
Table 17.1. Properties Used to Configure a JDBC Store Factory
Name | Description |
---|---|
clustered | Specifies if a datastore can be accessed by the members of an endpoint cluster. |
transactional | Specifies if the datastore can be enlisted in transactions. |
dataSource | Specifies the configuration for the data source to be used when creating the store. |
adapter | Specifies the configuration for the JDBC adapter used to connect to the data source. |
Example
Example 17.1. Configuring a Statefull JMS Provider Endpoint
<jms:provider service="tns:widgetServer" endpoint="widgetPort" storeFactory="#storeFactory"> 1 stateless="false" /> 2 <bean id="storeFactory" 3 class="org.apache.servicemix.store.jdbc.JdbcStoreFactory"> <property name="clustered" value="true"/> <property name="dataSource"> <ref local="mysql-ds"/> </property> </bean> <bean id="mysql-ds" 4 class="com.mchange.v2.c3p0.ComboPooledDataSource" destroy-method="close"> <property name="driverClass" value="com.mysql.jdbc.Driver"/> <property name="jdbcUrl" value="jdbc:mysql://localhost:3306/activemq?relaxAutoCommit=true"/> <property name="user" value="activemq"/> <property name="password" value="activemq"/> <property name="minPoolSize" value="5"/> <property name="maxPoolSize" value="10"/> <property name="acquireIncrement" value="3"/> <property name="autoCommitOnClose" value="false"/> </bean>
- 1
- Configures the endpoint's store factory by providing a reference to the bean configuring the factory.
- 2
- Configures the endpoint to store a copy of the current message in the datastore.
- 3
- Configures the JDBC factory store to create a datastore that can be accessed by a cluster of endpoints.
- 4
- Configures the MySQL JDBC driver.
Chapter 18. Working with Message Marshalers
Abstract
18.1. Consumer Marshalers
Overview
org.apache.servicemix.jms.endpoints.JmsConsumerMarshaler
interface to process the incoming JMS messages and convert them into normalized messages. Consumer marshalers also convert fault messages and response messages into JMS messages that can be returned to the remote endpoint. The JMS binding component comes with two consumer marshaler implementations:
DefaultConsumerMarshaler
- The
DefaultConsumerMarshaler
class provides the marshaler used by generic consumer endpoints and the JCA consumer endpoints. JmsSoapConsumerMarshaler
- The
JmsSoapConsumerMarshaler
class provides the marshaler used by SOAP consumer endpoints.NoteThe default SOAP marshaler does not support the full range of SOAP messages nor does it support marshaling map based messages into JMS messages.
JmsConsumerMarshaler
interface.
Implementing the marshaler
org.apache.servicemix.jms.endpoints.JmsConsumerMarshaler
interface. The JmsConsumerMarshaler
interface, shown in Example 18.1, “The Consumer Marshaler Interface”, has five methods that need implementing:
Example 18.1. The Consumer Marshaler Interface
public interface JmsConsumerMarshaler { public interface JmsContext { Message getMessage(); } JmsContext createContext(Message message) throws Exception; MessageExchange createExchange(JmsContext jmsContext, ComponentContext jbiContext) throws Exception; Message createOut(MessageExchange exchange, NormalizedMessage outMsg, Session session, JmsContext context) throws Exception; Message createFault(MessageExchange exchange, Fault fault, Session session, JmsContext context) throws Exception; Message createError(MessageExchange exchange, Exception error, Session session, JmsContext context) throws Exception; }
createContext()
- The
createContext()
method takes the JMS message and returns an object that implements theJmsContext
interface. createExchange()
- The
createExchange()
creates a message exchange using the JMS message and the JBI context. Creating a message exchange entails the creation of the exchange, populating the exchange's in message, specifying the message exchange pattern to use, and setting any other required properties. createOut()
- The
createOut()
method takes the response message from the message exchange and converts it into a JMS message. The method takes the message exchange, the outgoing message, the active JMS session, and the JMS context. createFault()
- The
createFault()
method is called if a fault message is returned. It takes the message exchange, the fault message, the active JMS session, and the JMS context and returns a JMS message that encapsulates the fault message. createError()
- The
createError()
method is called if an exception is thrown while the message exchange is being processed. It takes the message exchange, the exception, the active JMS session, and the JMS context and returns a JMS message that encapsulates the exception.
JmsContext
interface. The JmsContext
interface has a single method called getMessage()
which returns the JMS message contained in the context.
Example 18.2. Consumer Marshaler Implementation
package com.widgetVendor.example; import java.io.IOException; import java.io.ObjectInputStream; import java.io.ObjectOutputStream; import javax.jbi.component.ComponentContext; import javax.jbi.messaging.Fault; import javax.jbi.messaging.MessageExchange; import javax.jbi.messaging.NormalizedMessage; import javax.jms.Message; import javax.jms.Session; import javax.jms.TextMessage; import javax.xml.transform.Source; import org.apache.servicemix.jbi.jaxp.SourceTransformer; import org.apache.servicemix.jbi.jaxp.StringSource; import org.apache.servicemix.jbi.messaging.MessageExchangeSupport; public class widgetConsumerMarshaler implements JmsConsumerMarshaler { public JmsContext createContext(Message message) throws Exception { return new Context(message); } public MessageExchange createExchange(JmsContext jmsContext, ComponentContext jbiContext) throws Exception { Context ctx = (Context) jmsContext; MessageExchange exchange = jbiContext.getDeliveryChannel().createExchangeFactory().createExchange(MessageExchangeSupport.IN_ONLY); NormalizedMessage inMessage = exchange.createMessage(); TextMessage textMessage = (TextMessage) ctx.message; Source source = new StringSource(textMessage.getText()); inMessage.setContent(source); exchange.setMessage(inMessage, "in"); return exchange; } public Message createOut(MessageExchange exchange, NormalizedMessage outMsg, Session session, JmsContext context) throws Exception { String text = new SourceTransformer().contentToString(outMsg); return session.createTextMessage(text); } public Message createFault(MessageExchange exchange, Fault fault, Session session, JmsContext context) throws Exception { String text = new SourceTransformer().contentToString(fault); return session.createTextMessage(text); } public Message createError(MessageExchange exchange, Exception error, Session session, JmsContext context) throws Exception { throw error; } protected static class Context implements JmsContext { Message message; Context(Message message) { this.message = message; } public Message getMessage() { return this.message; } } }
Configuring the consumer
marshaler
attribute. The marshaler
attribute's value is a reference to a bean
element specifying the class of your custom marshaler implementation.
Example 18.3. Configuring a Consumer to Use a Customer Marshaler
<beans xmlns:jms="http://servicemix.apache.org/jms/1.0" ... > ... <jms:soap-consumer wsdl="classpath:widgets.wsdl" destinationName="widgetQueue" connectionFactory="#connectionFactory" marshaler="#myConsumerMarshaler" /> <bean id="myConsumerMarshaler" class="com.widgetVendor.example.widgetConsumerMarshaler" /> ... </beans>
marshaler
element to the consumer's configuration. The marshaler
element simply wraps the bean
element that configures the marshaler.
18.2. Provider Marshalers
Overview
org.apache.servicemix.jms.endpoints.JmsProviderMarshaler
interface to convert normalized messages into JMS messages. The marshaler also converts the incoming reply from a JMS message into a normalized message. The JMS binding component comes with two provider marshaler implementations:
DefaultProviderMarshaler
- The
DefaultProviderMarshaler
class provides the marshaler used by generic provider endpoints. JmsSoapProviderMarshaler
- The
JmsSoapProviderMarshaler
class provides the marshaler used by SOAP provider endpoints.NoteThe default SOAP marshaler does not support the full range of SOAP messages nor does it support marshaling map based messages into JMS messages.
JmsProviderMarshaler
interface.
Implementing the marshaler
org.apache.servicemix.jms.endpoints.JmsProviderMarshaler
interface. The JmsProviderMarshaler
interface, shown in Example 18.4, “The Provider Marshaler Interface”, has two methods you need to implement:
Example 18.4. The Provider Marshaler Interface
public interface JmsProviderMarshaler { Message createMessage(MessageExchange exchange, NormalizedMessage in, Session session) throws Exception; void populateMessage(Message message, MessageExchange exchange, NormalizedMessage normalizedMessage) throws Exception; }
createMessage()
- The
createMessage()
method uses information from the Red Hat JBoss Fuse core to generate a JMS message. Its parameters include the message exchange, the normalized message that is received by the provider, and the active JMS session. populateMessage()
- The
populateMessage()
method takes a JMS message and adds it to a message exchange for use by the Red Hat JBoss Fuse core.
Example 18.5. Provider Marshaler Implementation
package com.widgetVendor.example; import javax.jbi.messaging.MessageExchange; import javax.jbi.messaging.NormalizedMessage; import javax.jms.Message; import javax.jms.Session; import javax.jms.TextMessage; import javax.xml.transform.Source; import org.apache.servicemix.jbi.jaxp.SourceTransformer; import org.apache.servicemix.jbi.jaxp.StringSource; import org.apache.servicemix.jms.endpoints.JmsProviderMarshaler; public class widgetProviderMarshaler implements JmsProviderMarshaler { private SourceTransformer transformer = new SourceTransformer(); public Message createMessage(MessageExchange exchange, NormalizedMessage in, Session session) throws Exception { TextMessage text = session.createTextMessage(); text.setText(transformer.contentToString(in)); return text; } public void populateMessage(Message message, MessageExchange exchange, NormalizedMessage normalizedMessage) throws Exception { TextMessage textMessage = (TextMessage) message; Source source = new StringSource(textMessage.getText()); normalizedMessage.setContent(source); } }
Configuring the provider
marshaler
attribute. The marshaler
attribute's value is a reference to a bean
element specifying the class of your custom marshaler implementation.
Example 18.6. Configuring a Provider to Use a Customer Marshaler
<beans xmlns:jms="http://servicemix.apache.org/jms/1.0" ... > ... <jms:soap-provider wsdl="classpath:widgets.wsdl" destinationName="widgetQueue" connectionFactory="#connectionFactory" marshaler="#myProviderMarshaler" /> <bean id="myProviderMarshaler" class="com.widgetVendor.example.widgetProviderMarshaler" /> ... </beans>
marshaler
element to the provider's configuration. The marshaler
element simply wraps the bean
element that configures the marshaler.
Chapter 19. Implementing Destination Resolving Logic
Abstract
DestinationChooser
interface or the DestinationResolver
interface.
- destination choosers
- Destination choosers are specific to the Red Hat JBoss Fuse JMS binding component. They are the first mechanism used by an endpoint when it trys to pick a JMS destination.Destination choosers implement the
org.apache.servicemix.jms.endpoints.DestinationChooser
interface. - destination resolvers
- Destination resolvers are part of the Spring JMS framework. They are used when the JMS destination is specified using a string. This can happen if either the destination chooser returns a string or if the endpoint's destination is configured using the
destinationName
attribute.Destination resolvers implement theorg.springframework.jms.support.destination.DestinationResolver
interface.
19.1. Using a Custom Destination Chooser
Overview
org.apache.servicemix.jms.endpoints.DestinationChooser
interface and configure the endpoint to load it. The configured destination chooser will be used in place of the default destination chooser.
Implementing a destination chooser
org.apache.servicemix.jms.endpoints.DestinationChooser
interface. This interface has a single method: chooseDestination()
.
chooseDestination()
, whose signature is shown in Example 19.1, “Destination Chooser Method”, takes the JBI message exchange and a copy of the message. It returns either a JMS Destination
object or a string representing the destination name.
Example 19.1. Destination Chooser Method
Object chooseDestination(MessageExchange exchange,
Object message);
message
parameter can be either of the following type of object:
javax.jbi.messaging.NormalizedMessage
javax.jbi.messaging.Fault
Exception
Example 19.2. Simple Destination Chooser
package com.widgetVendor.example; import package org.apache.servicemix.jms.endpoints.DestinationChooser; import javax.jbi.messaging.MessageExchange; import javax.jbi.messaging.NormalizedMessage; import javax.jms.Destination; public class widgetDestinationChooser implements DestinationChooser { public static final String DESTINATION_KEY = "org.apache.servicemix.jms.destination"; public SimpleDestinationChooser() { } public Object chooseDestination(MessageExchange exchange, Object message) { Object property = null; if (message instanceof NormalizedMessage) { property = ((NormalizedMessage) message).getProperty(DESTINATION_KEY); } if (property instanceof Destination) { return (Destination) property; } if (property instanceof String) { return (String) property; } return new String("widgetDest"); } }
Configuring an endpoint to use a destination chooser
- Configure a
bean
element for your destination chooser. - Add a
destinationChooser
attribute that references the destination chooser's bean to your endpoint.
Example 19.3. Configuring a Destination Chooser with a Bean Reference
<beans xmlns:jms="http://servicemix.apache.org/jms/1.0"
... >
...
<jms:provider service="my:widgetService"
endpoint="jbiWidget"
destinationName="widgetQueue"
connectionFactory="#connectionFactory"
destinationChooser="#widgetDestinationChooser" />
<bean id="widgetDestinationChooser"
class="com.widgetVendor.example.widgetDestinationChooser" />
...
</beans>
jms:destinationChooser
element. This method is less flexible than the recommended method because other endpoints cannot reuse the destination chooser's configuration.
Example 19.4. Explicitly Configuring a Destination Chooser
<beans xmlns:jms="http://servicemix.apache.org/jms/1.0" ... > ... <jms:provider service="my:widgetService" endpoint="jbiWidget" destinationName="widgetQueue" connectionFactory="#connectionFactory"> <jms:destinationChooser> <bean id="widgetDestinationChooser" class="com.widgetVendor.example.widgetDestinationChooser" /> </jms:destinationChooser> </jms:provider> ... </beans>
19.2. Using a Custom Destination Resolver
Overview
Destination
objects. For example, if you specify an endpoint's destination using the destinationName
attribute, the endpoint will use a destination resolver to get the appropriate JMS Destination
object. Destination resolvers are also used if a destination chooser returns a string and not a JMS Destination
object.
DynamicDestinationResolver
destination resolver provided by the Spring Framework. This destination resolver uses the standard JMS Session.createTopic()
and Session.createQueue()
methods to resolve destination names.
JndiDestinationResolver
destination resolver. This destination resolver uses the string destination name to perform a JNDI lookup for the JMS destination. If JMS destination is not returned from the JNDI lookup, the resolver resorts to dynamically resolving the destination name. For information on configuring and endpoint to use the JndiDestinationResolver
destination resolver. See the section called “Configuring an endpoint to use a destination resolver”.
Implementing a destination resolver
org.springframework.jms.support.destination.DestinationResolver
interface. The interface has a single method: resolveDestinationName()
.
resolveDestinationName()
method, whose signature shown in Example 19.5, “Destination Resolver Method”, takes three parameters: a JMS session, a destination name, and a boolean specifying if the destination is a JMS topic.[2] It returns a JMS destination that correlates to the provided destination name.
Example 19.5. Destination Resolver Method
Destination resolveDestinationName(Session session,
String destinationName,
boolean pubSubDomain)
throws JMSException;
Example 19.6. Simple Destination Resolver
package com.widgetVendor.example; import org.springframework.jms.support.destination.DestinationResolver; import javax.jms.Destination; import javax.jms.JMSException; import javax.jms.Session; public class widgetDestinationResolver implements DestinationResolver { public Destination resolveDestinationName(Session session, String destinationName, boolean pubSubDomain) throws JMSException { if (pubSubDomain) { return session.createTopic(destinationName); } else { return session.createQueue(destinationName); } } }
Configuring an endpoint to use a destination resolver
- Configure a
bean
element for your destination resolver. - Add a
destinationResolver
attribute that references the destination resolver's bean to your endpoint.
Example 19.7. Configuring a Destination Resolver with a Bean Reference
<beans xmlns:jms="http://servicemix.apache.org/jms/1.0"
... >
...
<jms:consumer service="my:widgetService"
endpoint="jbiWidget"
destinationName="widgetQueue"
connectionFactory="#connectionFactory"
destinationResolver="#widgetDestinationResolver" />
<bean id="widgetDestinationResolver"
class="com.widgetVendor.example.widgetDestinationResolver" />
...
</beans>
jms:destinationResolver
element. This method is less flexible than the recommended method because other endpoints cannot reuse the destination resolver's configuration.
Example 19.8. Explicitly Configuring a Destination Resolver
<beans xmlns:jms="http://servicemix.apache.org/jms/1.0" ... > ... <jms:consumer service="my:widgetService" endpoint="jbiWidget" destinationName="widgetQueue" connectionFactory="#connectionFactory"> <jms:destinationResolver> <bean id="widgetDestinationResolver" class="com.widgetVendor.example.widgetDestinationResolver" /> </jms:destinationChooser> </jms:consumer> ... </beans>
Appendix D. Consumer Endpoint Properties
D.1. Common Properties
Attributes
Table D.1. Common Consumer Endpoint Property Attributes
Name | Type | Description | Required |
---|---|---|---|
connectionFactory | string | Specifies a reference to the bean configuring the connection factory which is to be used by the endpoint. | yes |
service | QName | Specifies the service name of the proxied endpoint. | yes |
endpoint | string | Specifies the endpoint name of the proxied endpoint. | yes |
interfaceName | QName | Specifies the interface name of the proxied endpoint. | no |
jms102 | boolean | Specifies if the consumer uses JMS 1.0.2 compliant APIs. | no (defaults to false ) |
pubSubDomaim | boolean | Specifies if the destination is a topic. | no |
replyDeliveryMode | int | Specifies the JMS delivery mode used for the reply. | no (defaults to PERSISTENT (2)) |
replyDestinationName | string | Specifies the name of the JMS destination to use for the reply. | no (if not set replyDestination or destinationChooser is used) |
replyExplicitQosEnabled | boolean | Specifies if the QoS values specified for the endpoint are explicitly used when the reply is sent. | no (default is false) |
replyPriority | int | Specifies the JMS message priority of the reply. | no (defaults to 4) |
replyTimeToLive | long | Specifies the number of milliseconds the reply message is valid. | no (defaults to unlimited) |
stateless | boolean | Specifies if the consumer retains state information about the message exchange while it is in process. | no |
synchronous | boolean | Specifies if the consumer will block while waiting for a response. This means the consumer can only process one message at a time. | no (defaults to true) |
targetEndpoint | string | Specifies the endpoint name of the target endpoint. | no (defaults to the endpoint attribute) |
targetInterface | QName | Specifies the interface name of the target endpoint. | no |
targetService | QName | Specifies the service name of the target endpoint. | no (defaults to the service attribute) |
targetUri | string | Specifies the URI of the target endpoint. | no |
useMessageIdInResponse | boolean | Specifies if the request message's ID is used as the reply's correlation ID. | no (defaults to false meaning the request's correlation ID is used) |
Beans
Table D.2. Common Consumer Endpoint Property Beans
Name | Type | Description | Required |
---|---|---|---|
marshaler | JmsConsumerMarshaler | Specifies the class implementing the message marshaler. | no (defaults to DefaultConsumerMarshaler ) |
destinationChooser | DestinationChooser | Specifies a class implementing logic for choosing reply destinations. | no |
destinationResolver | DestinationResolver | Specifies the class implementing logic for converting strings into destination IDs. | no (defaults to DynamicDestinationResolver ) |
replyDestination | Destination | Specifies the JMS destination for the replies. | no (if not set either the replyDestinationName or the destinationChooser is used) |
replyProperties | Map | Specifies custom properties to be placed in the reply's JMS header. | no |
storeFactory | StoreFactory | Specifies the factory class used to create the data store for state information. | no (defaults to MemoryStoreFactory ) |
store | Store | Specifies the data store used to store state information. | no |
D.2. Properties Specific to Generic Consumers and SOAP Consumers
Common Attributes
jms:consumer
element and the jms:soap-consumer
elements.
Table D.3. Attributes Uses to Configure Standard JMS Consumers and SOAP JMS Consumers
Attribute | Type | Listener(s) | Description | Required |
---|---|---|---|---|
listenerType | string | all | Specifies the type of Spring JMS message listener to use. Valid values are default , simple , and server . | no (defaults to default ) |
transacted | string | all | Specifies the type of transaction used to wrap the message exchanges. Valid values are none , xa , and jms . | no (defaults to none ) |
clientId | string | all | Specifies the JMS client id for a shared Connection created and used by this listener. | no |
destinationName | string | all | Specifies the name of the destination used to receive messages. | no |
durableSubscriptionName | string | all | Specifies the name used to register the durable subscription. | no |
messageSelector | string | all | Specifies the message selector string to use. | no |
sessionAcknowlegeMode | int | all | Specifies the acknowledgment mode that is used when creating a Session to send a message. | no (defaults to Session.AUTO_ACKNOWLEDGE ) |
subscriptionDurable | boolean | all | Specifies if the listener uses a durable subscription to listen form messages. | no (defaults to false ) |
pubSubNoLocal | boolean |
default
simple
| Specifies if messages published by the listener's Connection are suppressed. | no (defaults to false ) |
concurrentConsumers | int |
default
simple
| Specifies the number of concurrent consumers created by the listener. | no (defaults to 1 ) |
cacheLevel | int | default | Specifies the level of caching allowed by the listener. | no (defaults to 0 ) |
receiveTimeout | long | default | Specifies the timeout for receiving a message in milliseconds. | no (default is 1000 ) |
recoveryInterval | long | default | Specifies the interval, in milliseconds, between attempts to recover after a failed listener set-up. | no (defaults to 5000 ) |
maxMessagesPerTask | int |
default
server
| Specifies the number of attempts to receive messages per task. | no (defaults to -1 ) |
Common Beans
jms:consumer
element and the jms:soap-consumer
elements.
Table D.4. Elements Uses to Configure Standard JMS Consumers and SOAP JMS Consumers
Element | Type | Listener(s) | Description | Required |
---|---|---|---|---|
destination | Destination | all | Specifies the destination used to receive messages. | no |
exceptionListener | ExceptionListener | all | Specifies an ExceptionListener to notify in case of a JMSException is thrown by the registered message listener or the invocation infrastructure. | no |
serverSessionFactory | ServerSessionFactory | server | Specifies the ServerSessionFactory to use. | no (defaults to SimpleServerSessionFactory ) |
SOAP consumer specific attributes
jms:soap-consumer
element.
Table D.5. Attributes for the JMS SOAP Consumer
Attribute | Type | Description | Required |
---|---|---|---|
wsdl | string | Specifies the WSDL describing the service. | yes |
useJbiWrapper | boolean | Specifies if the JBI wrapper is sent in the body of the message. | no (defaults to true ) |
validateWsdl | boolean | Specifies if the WSDL is checked WSI-BP compliance. | no (defaults to true ) |
policies | Policy[] | Specifies a list of interceptors used to process the message. | no |
D.3. Properties Specific to a JCA Consumer
jms:jca-consumer
element.
Table D.6. Elements Used to Configure a JCA Consumer
Element | Type | Description | Required |
---|---|---|---|
resourceAdapter | ResourceAdapter | Specifies the resource adapter used for the endpoint. | yes |
activationSpec | ActivationSpec | Specifies the activation information needed by the endpoint. | yes |
bootstrapContext | BootstrapContext | Specifies the bootstrap context used when starting the resource adapter. | no (a default one will be created) |
Appendix E. Provider Endpoint Properties
E.1. Common Properties
Attributes
Table E.1. Common Provider Endpoint Property Attributes
Attribute | Type | Description | Required |
---|---|---|---|
connectionFactory | string | Specifies a reference to the bean which configure the connection factory to be used by the endpoint. | yes |
deliveryMode | int | Specifies the JMS delivery mode. | no (defaults to persistent) |
destinationName | string | Specifies the JNDI name of the destination used to send messages. | no |
endpoint | string | Specifies the endpoint name of the proxied endpoint. | yes |
explicitQosEnabled | boolean | Specifies if the JMS messages have the specified properties explicitly applied. | no (defaults to false ) |
interfaceName | QName | Specifies the interface name of the proxied endpoint. | no |
jms102 | boolean | Specifies if the provider is to be JMS 1.0.2 compatible. | no (defaults to false ) |
messageIdEnabled | boolean | Specifies if JMS message IDs are enabled. | no (defaults to true ) |
messageTimeStampEnabled | boolean | Specifies if JMS messages are time stamped. | no (defaults to true ) |
priority | int | Specifies the priority assigned to the JMS messages. | no (defaults to 4 ) |
pubSubDomain | boolean | Specifies if the destination is a topic. | no (defaults to false |
pubSubNoLocal | boolean | Specifies if messages published by the listener's Connection are suppressed. | no (defaults to false ) |
recieveTimeout | long | Specifies the timeout for receiving a message in milliseconds. | no (defaults to unlimited) |
replyDestinationName | string | Specifies the JNDI name of the destination used to receive messages. | no |
service | QName | Specifies the service name of the proxied endpoint. | yes |
stateless | boolean | Specifies if the consumer retains state information about the message exchange while it is in process. | no (defaults to false ) |
timeToLive | long | Specifies the number of milliseconds the message is valid. | no (defaults to unlimited) |
Beans
Table E.2. Common Provider Endpoint Property Beans
Element | Type | Description | Required |
---|---|---|---|
destination | Destination | Specifies the JMS destination used to send messages. | no |
destinationChooser | DestinationChooser | Specifies a class implementing logic for choosing the JMS destinations. | no (defaults to SimpleDestinationChooser ) |
destinationResolver | DestinationResolver | Specifies a class implementing logic for converting strings into destination IDs. | no (defaults to DynamicDestinationResolver ) |
marshaler | JmsProviderMarshaler | Specifies the class implementing the message marshaler. | no (defaults to DefaultProviderMarshaler or JmsSoapProviderMarshaler ) |
replyDestination | Destination | Specifies the JMS destination used to receive messages. | no |
replyDestinationChooser | DestinationChooser | Specifies a class implementing logic for choosing the destination used to receive replies. | no (defaults to SimpleDestinationChooser ) |
storeFactory | StoreFactory | Specifies the factory class used to create the data store for state information. | no (defaults to MemoryStoreFactory ) |
store | Store | Specifies the data store used to store state information. | no |
E.2. Properties Specific to SOAP Providers
Attributes
jms:soap-provider
elements.
Table E.3. Attributes Used to Configure SOAP JMS Providers
Attribute | Type | Description | Required |
---|---|---|---|
useJbiWrapper | boolean | Specifies if the JBI wrapper is sent in the body of the message. | no (defaults to true ) |
validateWsdl | boolean | Specifies if the WSDL is checked for WSI-BP compliance. | no (defaults to true ) |
wsdl | string | Specifies the location of the WSDL describing the service. | yes |
Beans
jms:soap-provider
elements.
Table E.4. Elements Used to Configure SOAP JMS Providers
Element | Type | Description | Required |
---|---|---|---|
policies | Policy[] | Specifies a list of interceptors that will process the message. | no |
Part IV. CXF Binding Component
Abstract
Chapter 20. Introduction to the Apache CXF Binding Component
Abstract
Overview
- consumer endpoint
- A consumer endpoint listens for messages on a specified address. When it receives a message it sends it to the NMR for delivery to the appropriate endpoint. If the message is part of a two-way exchange, then the consumer endpoint is also responsible for returning the response to the external endpoint.For information about configuring consumer endpoints see Chapter 28, Consumer Endpoints.
- provider endpoint
- A provider endpoint receives messages from the NMR. It then packages the message as a SOAP message and sends it to the specified external address. If the message is part of a two-way message exchange, the provider endpoint waits for the response from the external endpoint. The provider endpoint will then direct the response back to the NMR.For information about configuring provider endpoints see Chapter 29, Provider Endpoints.
Key features
- HTTP support
- JMS 1.1 support
- SOAP 1.1 support
- SOAP 1.2 support
- MTOM support
- Support for all MEPs as consumers or providers
- SSL support
- WS-Security support
- WS-Policy support
- WS-RM support
- WS-Addressing support
Steps for working with the Apache CXF binding component
More information
Chapter 21. Introducing WSDL Contracts
Abstract
21.1. Structure of a WSDL document
definition
element. These elements describe a service and how an endpoint implementing that service is accessed.
- A logical part that defines the service in implementation neutral terms
- A concrete part that defines how an endpoint implementing the service is exposed on a network
The logical part
types
, the message
, and the portType
elements. It describes the service’s interface and the messages exchanged by the service. Within the types
element, XML Schema is used to define the structure of the data that makes up the messages. A number of message
elements are used to define the structure of the messages used by the service. The portType
element contains one or more operation
elements that define the messages sent by the operations exposed by the service.
The concrete part
binding
and the service
elements. It describes how an endpoint that implements the service connects to the outside world. The binding
elements describe how the data units described by the message
elements are mapped into a concrete, on-the-wire data format, such as SOAP. The service
elements contain one or more port
elements which define the endpoints implementing the service.
21.2. WSDL elements
definitions
— The root element of a WSDL document. The attributes of this element specify the name of the WSDL document, the document’s target namespace, and the shorthand definitions for the namespaces referenced in the WSDL document.types
— The XML Schema definitions for the data units that form the building blocks of the messages used by a service. For information about defining data types see Chapter 22, Defining Logical Data Units.message
— The description of the messages exchanged during invocation of a services operations. These elements define the arguments of the operations making up your service. For information on defining messages see Chapter 23, Defining Logical Messages Used by a Service.portType
— A collection ofoperation
elements describing the logical interface of a service. For information about defining port types see Chapter 24, Defining Your Logical Interfaces.operation
— The description of an action performed by a service. Operations are defined by the messages passed between two endpoints when the operation is invoked. For information on defining operations see the section called “Operations”.binding
— The concrete data format specification for an endpoint. Abinding
element defines how the abstract messages are mapped into the concrete data format used by an endpoint. This element is where specifics such as parameter order and return values are specified.service
— A collection of relatedport
elements. These elements are repositories for organizing endpoint definitions.port
— The endpoint defined by a binding and a physical address. These elements bring all of the abstract definitions together, combined with the definition of transport details, and they define the physical endpoint on which a service is exposed.
21.3. Designing a contract
- Define the data types used by your services.
- Define the messages used by your services.
- Define the interfaces for your services.
- Define the bindings between the messages used by each interface and the concrete representation of the data on the wire.
- Define the transport details for each of the services.
Chapter 22. Defining Logical Data Units
Abstract
- Breaking the data into logical units that can be mapped into the data types used by the physical implementations of the service
- Combining the logical units into messages that are passed between endpoints to carry out the operations
22.1. Mapping data into logical data units
Available type systems for defining service data units
XML Schema as a type system
Considerations for creating your data units
- Use elements, not attributes.
- Do not use protocol-specific types as base types.
22.2. Adding data units to a contract
Procedure
- Determine all the data units used in the interface described by the contract.
- Create a
types
element in your contract. - Create a
schema
element, shown in Example 22.1, “Schema entry for a WSDL contract”, as a child of thetype
element.ThetargetNamespace
attribute specifies the namespace under which new data types are defined. The remaining entries should not be changed.Example 22.1. Schema entry for a WSDL contract
<schema targetNamespace="http://schemas.iona.com/bank.idl" xmlns="http://www.w3.org/2001/XMLSchema" xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/">
- For each complex type that is a collection of elements, define the data type using a
complexType
element. See Section 22.4.1, “Defining data structures”. - For each array, define the data type using a
complexType
element. See Section 22.4.2, “Defining arrays”. - For each complex type that is derived from a simple type, define the data type using a
simpleType
element. See Section 22.4.4, “Defining types by restriction”. - For each enumerated type, define the data type using a
simpleType
element. See Section 22.4.5, “Defining enumerated types”. - For each element, define it using an
element
element. See Section 22.5, “Defining elements”.
22.3. XML Schema simple types
Entering simple types
element
elements used in the types section of your contract. They are also used in the base
attribute of restriction
elements and extension
elements.
xsd
prefix. For example, to specify that an element is of type int, you would enter xsd:int in its type
attribute as shown in Example 22.2, “Defining an element with a simple type”.
Example 22.2. Defining an element with a simple type
<element name="simpleInt" type="xsd:int" />
Supported XSD simple types
- xsd:string
- xsd:normalizedString
- xsd:int
- xsd:unsignedInt
- xsd:long
- xsd:unsignedLong
- xsd:short
- xsd:unsignedShort
- xsd:float
- xsd:double
- xsd:boolean
- xsd:byte
- xsd:unsignedByte
- xsd:integer
- xsd:positiveInteger
- xsd:negativeInteger
- xsd:nonPositiveInteger
- xsd:nonNegativeInteger
- xsd:decimal
- xsd:dateTime
- xsd:time
- xsd:date
- xsd:QName
- xsd:base64Binary
- xsd:hexBinary
- xsd:ID
- xsd:token
- xsd:language
- xsd:Name
- xsd:NCName
- xsd:NMTOKEN
- xsd:anySimpleType
- xsd:anyURI
- xsd:gYear
- xsd:gMonth
- xsd:gDay
- xsd:gYearMonth
- xsd:gMonthDay
22.4. Defining complex data types
22.4.1. Defining data structures
complexType
elements. Specifying a complex type requires three pieces of information:
- The name of the defined type is specified in the
name
attribute of thecomplexType
element. - The first child element of the
complexType
describes the behavior of the structure’s fields when it is put on the wire. See the section called “Complex type varieties”. - Each of the fields of the defined structure are defined in
element
elements that are grandchildren of thecomplexType
element. See the section called “Defining the parts of a structure”.
Example 22.3. Simple Structure
struct personalInfo { string name; int age; };
Example 22.4. A complex type
<complexType name="personalInfo"> <sequence> <element name="name" type="xsd:string" /> <element name="age" type="xsd:int" /> </sequence> </complexType>
Complex type varieties
complexType
element determines which variety of complex type is being used. Table 22.1, “Complex type descriptor elements” shows the elements used to define complex type behavior.
Table 22.1. Complex type descriptor elements
sequence
element, an all
element, or a choice
is not specified, then a sequence
is assumed. For example, the structure defined in Example 22.4, “A complex type” generates a message containing two elements: name
and age
.
choice
element, as shown in Example 22.5, “Simple complex choice type”, it generates a message with either a name
element or an age
element.
Example 22.5. Simple complex choice type
<complexType name="personalInfo"> <choice> <element name="name" type="xsd:string"/> <element name="age" type="xsd:int"/> </choice> </complexType>
Defining the parts of a structure
element
elements. Every complexType
element should contain at least one element
element. Each element
element in the complexType
element represents a field in the defined data structure.
element
elements have two required attributes:
name
and type
, element
elements have two other commonly used optional attributes: minOcurrs
and maxOccurs
. These attributes place bounds on the number of times the field occurs in the structure. By default, each field occurs only once in a complex type. Using these attributes, you can change how many times a field must or can appear in a structure. For example, you can define a field, previousJobs
, that must occur at least three times, and no more than seven times, as shown in Example 22.6, “Simple complex type with occurrence constraints”.
Example 22.6. Simple complex type with occurrence constraints
<complexType name="personalInfo> <all> <element name="name" type="xsd:string"/> <element name="age" type="xsd:int"/> <element name="previousJobs" type="xsd:string: minOccurs="3" maxOccurs="7"/> </all> </complexType>
minOccurs
to make the age
field optional by setting the minOccurs
to zero as shown in Example 22.7, “Simple complex type with minOccurs set to zero”. In this case age
can be omitted and the data will still be valid.
Example 22.7. Simple complex type with minOccurs set to zero
<complexType name="personalInfo> <choice> <element name="name" type="xsd:string"/> <element name="age" type="xsd:int" minOccurs="0"/> </choice> </complexType>
Defining attributes
complexType
element name
is an attribute. They are specified using the attribute
element. It comes after the all
, sequence
, or choice
element and are a direct child of the complexType
element. Example 22.8, “Complex type with an attribute” shows a complex type with an attribute.
Example 22.8. Complex type with an attribute
<complexType name="personalInfo> <all> <element name="name" type="xsd:string"/> <element name="previousJobs" type="xsd:string" minOccurs="3" maxOccurs="7"/> </all> <attribute name="age" type="xsd:int" use="optional" /> </complexType>
attribute
element has three attributes:
default
. The default
attribute allows you to specify a default value for the attribute.
22.4.2. Defining arrays
maxOccurs
attribute has a value greater than one. The second is to use SOAP arrays. SOAP arrays provide added functionality such as the ability to easily define multi-dimensional arrays and to transmit sparsely populated arrays.
Complex type arrays
maxOccurs
attribute. For example, to define an array of twenty floating point numbers you use a complex type similar to the one shown in Example 22.9, “Complex type array”.
Example 22.9. Complex type array
<complexType name="personalInfo"> <element name="averages" type="xsd:float" maxOccurs="20"/> </complexType>
minOccurs
attribute.
SOAP arrays
wsdl:arrayType
element. The syntax for this is shown in Example 22.10, “Syntax for a SOAP array derived using wsdl:arrayType”.
Example 22.10. Syntax for a SOAP array derived using wsdl:arrayType
<complexType name="TypeName"> <complexContent> <restriction base="SOAP-ENC:Array"> <attribute ref="SOAP-ENC:arrayType" wsdl:arrayType="ElementType<ArrayBounds>"/> </restriction> </complexContent> </complexType>
[]
; to specify a two-dimensional array use either [][]
or [,]
.
wsdl:arrayType
attribute specifies the type of the array elements, xsd:string, and the number of dimensions, with []
implying one dimension.
Example 22.11. Definition of a SOAP array
<complexType name="SOAPStrings"> <complexContent> <restriction base="SOAP-ENC:Array"> <attribute ref="SOAP-ENC:arrayType" wsdl:arrayType="xsd:string[]"/> </restriction> </complexContent> </complexType>
Example 22.12. Syntax for a SOAP array derived using an element
<complexType name="TypeName"> <complexContent> <restriction base="SOAP-ENC:Array"> <sequence> <element name="ElementName" type="ElementType" maxOccurs="unbounded"/> </sequence> </restriction> </complexContent> </complexType>
maxOccurs
attribute must always be set to unbounded
.
22.4.3. Defining types by extension
alienInfo
, that extends the personalInfo
structure defined in Example 22.4, “A complex type” by adding a new element called planet
.
- The name of the type is defined by the
name
attribute of thecomplexType
element. - The
complexContent
element specifies that the new type will have more than one element.NoteIf you are only adding new attributes to the complex type, you can use asimpleContent
element. - The type from which the new type is derived, called the base type, is specified in the
base
attribute of theextension
element. - The new type’s elements and attributes are defined in the
extension
element, the same as they are for a regular complex type.
alienInfo
is defined as shown in Example 22.13, “Type defined by extension”.
Example 22.13. Type defined by extension
<complexType name="alienInfo"> <complexContent> <extension base="personalInfo"> <sequence> <element name="planet" type="xsd:string"/> </sequence> </extension> </complexContent> </complexType>
22.4.4. Defining types by restriction
SSN
, which is a string of exactly nine characters. New types defined by restricting simple types are defined using a simpleType
element.
- The name of the new type is specified by the
name
attribute of thesimpleType
element. - The simple type from which the new type is derived, called the base type, is specified in the
restriction
element. See the section called “Specifying the base type”. - The rules, called facets, defining the restrictions placed on the base type are defined as children of the
restriction
element. See the section called “Defining the restrictions”.
Specifying the base type
restriction
element. The restriction
element is the only child of a simpleType
element and has one attribute, base
, that specifies the base type. The base type can be any of the XML Schema simple types.
Example 22.14. Using int as the base type
<simpleType name="restrictedInt"> <restriction base="xsd:int"> ... </restriction> </simpleType>
Defining the restrictions
value
, that defines how the facet is enforced. The available facets and their valid value
settings depend on the base type. For example, xsd:string supports six facets, including:
length
minLength
maxLength
pattern
whitespace
enumeration
restriction
element.
Example
SSN
, which represents a social security number. The resulting type is a string of the form xxx-xx-xxxx
. <SSN>032-43-9876<SSN> is a valid value for an element of this type, but <SSN>032439876</SSN> is not.
Example 22.15. SSN simple type description
<simpleType name="SSN"> <restriction base="xsd:string"> <pattern value="\d{3}-\d{2}-\d{4}"/> </restriction> </simpleType>
22.4.5. Defining enumerated types
enumeration
facet which is supported by all XML Schema primitive types. As with enumerated types in most modern programming languages, a variable of this type can only have one of the specified values.
Defining an enumeration in XML Schema
Example 22.16. Syntax for an enumeration
<simpleType name="EnumName"> <restriction base="EnumType"> <enumeration value="Case1Value"/> <enumeration value="Case2Value"/> ... <enumeration value="CaseNValue"/> </restriction> </simpleType>
Example
widgetSize
, shown in Example 22.17, “widgetSize enumeration”, would be valid if it contained <widgetSize>big</widgetSize>, but it would not be valid if it contained <widgetSize>big,mungo</widgetSize>.
Example 22.17. widgetSize enumeration
<simpleType name="widgetSize"> <restriction base="xsd:string"> <enumeration value="big"/> <enumeration value="large"/> <enumeration value="mungo"/> </restriction> </simpleType>
22.5. Defining elements
element
element. Like the element
element used to define the members of a complex type, they have three attributes:
name
— A required attribute that specifies the name of the element as it appears in an XML document.type
— Specifies the type of the element. The type can be any XML Schema primitive type or any named complex type defined in the contract. This attribute can be omitted if the type has an in-line definition.nillable
— Specifies whether an element can be omitted from a document entirely. Ifnillable
is set totrue
, the element can be omitted from any document generated using the schema.
complexType
element or a simpleType
element. Once you specify if the type of data is complex or simple, you can define any type of data needed using the tools available for each type of data. In-line type definitions are discouraged because they are not reusable.
Chapter 23. Defining Logical Messages Used by a Service
Abstract
message
element. The messages are made up of one or more parts that are defined using part
elements.
message
element in your contracts. Each logical message consists of one or more parts, defined in part
elements.
Messages and parameter lists
Message design for integrating with legacy systems
types
element of the contract. Your input message contains one part for each input parameter in the method. Your output message contains one part for each output parameter, plus a part to represent the return value, if needed. If a parameter is both an input and an output parameter, it is listed as a part for both the input message and the output message.
Message design for SOAP services
types
element of the contract. The wrapper element has the following characteristics:
- It is a complex type containing a sequence of elements. For more information see Section 22.4, “Defining complex data types”.
- If it is a wrapper for an input message:
- It has one element for each of the method’s input parameters.
- Its name is the same as the name of the operation with which it is associated.
- If it is a wrapper for an output message:
- It has one element for each of the method’s output parameters and one element for each of the method’s inout parameters.
- Its first element represents the method’s return parameter.
- Its name would be generated by appending
Response
to the name of the operation with which the wrapper is associated.
Message naming
- Messages should only be used by a single operation.
- Input message names are formed by appending
Request
to the name of the operation. - Output message names are formed by appending
Response
to the name of the operation. - Fault message names should represent the reason for the fault.
Message parts
part
element, and is identified by a name
attribute and either a type
attribute or an element
attribute that specifies its data type. The data type attributes are listed in Table 23.1, “Part data type attributes”.
Table 23.1. Part data type attributes
foo
, that is passed by reference or is an in/out, it can be a part in both the request message and the response message, as shown in Example 23.1, “Reused part”.
Example 23.1. Reused part
<message name="fooRequest"> <part name="foo" type="xsd:int"/> <message> <message name="fooReply"> <part name="foo" type="xsd:int"/> <message>
Example
Example 23.2. personalInfo lookup method
personalInfo lookup(long empId)
Example 23.3. RPC WSDL message definitions
<message name="personalLookupRequest"> <part name="empId" type="xsd:int"/> <message/> <message name="personalLookupResponse> <part name="return" element="xsd1:personalInfo"/> <message/>
Example 23.4. Wrapped document WSDL message definitions
<types> <schema ... > ... <element name="personalLookup"> <complexType> <sequence> <element name="empID" type="xsd:int" /> </sequence> </complexType> </element> <element name="personalLookupResponse"> <complexType> <sequence> <element name="return" type="personalInfo" /> </sequence> </complexType> </element> </schema> </types> <message name="personalLookupRequest"> <part name="empId" element="xsd1:personalLookup"/> <message/> <message name="personalLookupResponse"> <part name="return" element="xsd1:personalLookupResponse"/> <message/>
Chapter 24. Defining Your Logical Interfaces
Abstract
portType
element.
portType
element. The portType
element is a collection of abstract operation definitions. Each operation is defined by the input, output, and fault messages used to complete the transaction the operation represents. When code is generated to implement the service interface defined by a portType
element, each operation is converted into a method containing the parameters defined by the input, output, and fault messages specified in the contract.
Process
- Create a
portType
element to contain the interface definition and give it a unique name. See the section called “Port types”. - Create an
operation
element for each operation defined in the interface. See the section called “Operations”. - For each operation, specify the messages used to represent the operation’s parameter list, return type, and exceptions. See the section called “Operation messages”.
Port types
portType
element is the root element in a logical interface definition. While many Web service implementations map portType
elements directly to generated implementation objects, a logical interface definition does not specify the exact functionality provided by the the implemented service. For example, a logical interface named ticketSystem
can result in an implementation that either sells concert tickets or issues parking tickets.
portType
element is the unit of a WSDL document that is mapped into a binding to define the physical data used by an endpoint exposing the defined service.
portType
element in a WSDL document must have a unique name, which is specified using the name
attribute, and is made up of a collection of operations, which are described in operation
elements. A WSDL document can describe any number of port types.
Operations
operation
elements, define the interaction between two endpoints. For example, a request for a checking account balance and an order for a gross of widgets can both be defined as operations.
portType
element must have a unique name, specified using the name
attribute. The name
attribute is required to define an operation.
Operation messages
Table 24.1. Operation message elements
Element | Description |
---|---|
input | Specifies the message the client endpoint sends to the service provider when a request is made. The parts of this message correspond to the input parameters of the operation. |
output | Specifies the message that the service provider sends to the client endpoint in response to a request. The parts of this message correspond to any operation parameters that can be changed by the service provider, such as values passed by reference. This includes the return value of the operation. |
fault | Specifies a message used to communicate an error condition between the endpoints. |
input
or one output
element. An operation can have both input
and output
elements, but it can only have one of each. Operations are not required to have any fault
elements, but can, if required, have any number of fault
elements.
Table 24.2. Attributes of the input and output elements
Attribute | Description |
---|---|
name | Identifies the message so it can be referenced when mapping the operation to a concrete data format. The name must be unique within the enclosing port type. |
message | Specifies the abstract message that describes the data being sent or received. The value of the message attribute must correspond to the name attribute of one of the abstract messages defined in the WSDL document. |
name
attribute for all input
and output
elements; WSDL provides a default naming scheme based on the enclosing operation’s name. If only one element is used in the operation, the element name defaults to the name of the operation. If both an input
and an output
element are used, the element name defaults to the name of the operation with either Request
or Response
respectively appended to the name.
Return values
operation
element is an abstract definition of the data passed during an operation, WSDL does not provide for return values to be specified for an operation. If a method returns a value it will be mapped into the output
element as the last part of that message.
Example
Example 24.1. personalInfo lookup interface
interface personalInfoLookup { personalInfo lookup(in int empID) raises(idNotFound); }
Example 24.2. personalInfo lookup port type
<message name="personalLookupRequest"> <part name="empId" element="xsd1:personalLookup"/> <message/> <message name="personalLookupResponse"> <part name="return" element="xsd1:personalLookupResponse"/> <message/> <message name="idNotFoundException"> <part name="exception" element="xsd1:idNotFound"/> <message/> <portType name="personalInfoLookup"> <operation name="lookup"> <input name="empID" message="personalLookupRequest"/> <output name="return" message="personalLookupResponse"/> <fault name="exception" message="idNotFoundException"/> </operation> </portType>
Chapter 25. Using HTTP
Abstract
25.1. Adding a Basic HTTP Endpoint
Overview
- SOAP 1.1 uses the standardized
soap:address
element. - SOAP 1.2 uses the
soap12:address
element. - All other payload formats use the
http:address element.
SOAP 1.1
address
element to specify the endpoint’s address. It has one attribute, location
, that specifies the endpoint’s address as a URL. The SOAP 1.1 address
element is defined in the namespace http://schemas.xmlsoap.org/wsdl/soap/.
port
element used to send SOAP 1.1 messages over HTTP.
Example 25.1. SOAP 1.1 Port Element
<definitions ... xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" ...> ... <service name="SOAP11Service"> <port binding="SOAP11Binding" name="SOAP11Port"> <soap:address location="http://artie.com/index.xml"> </port> </service> ... <definitions>
SOAP 1.2
address
element to specify the endpoint’s address. It has one attribute, location
, that specifies the endpoint’s address as a URL. The SOAP 1.2 address
element is defined in the namespace http://schemas.xmlsoap.org/wsdl/soap12/.
port
element used to send SOAP 1.2 messages over HTTP.
Example 25.2. SOAP 1.2 Port Element
<definitions ... xmlns:soap12="http://schemas.xmlsoap.org/wsdl/soap12/" ... > <service name="SOAP12Service"> <port binding="SOAP12Binding" name="SOAP12Port"> <soap12:address location="http://artie.com/index.xml"> </port> </service> ... </definitions>
Other messages types
address
element to specify the endpoint’s address. It has one attribute, location
, that specifies the endpoint’s address as a URL. The HTTP address
element is defined in the namespace http://schemas.xmlsoap.org/wsdl/http/.
port
element used to send an XML message.
Example 25.3. HTTP Port Element
<definitions ... xmlns:http="http://schemas.xmlsoap.org/wsdl/http/" ... > <service name="HTTPService"> <port binding="HTTPBinding" name="HTTPPort"> <http:address location="http://artie.com/index.xml"> </port> </service> ... </definitions>
25.2. Consumer Configuration
Namespace
http-conf
. In order to use the HTTP configuration elements you must add the line shown in Example 25.4, “HTTP Consumer WSDL Element's Namespace” to the definitions
element of your endpoint's WSDL document.
Example 25.4. HTTP Consumer WSDL Element's Namespace
<definitions ... xmlns:http-conf="http://cxf.apache.org/transports/http/configuration"
Configuring the endpoint
http-conf:client
element is used to specify the connection properties of an HTTP consumer in a WSDL document. The http-conf:client
element is a child of the WSDL port
element. The attributes are described in Table 25.1, “HTTP Consumer Configuration Attributes”.
Table 25.1. HTTP Consumer Configuration Attributes
Attribute | Description |
---|---|
ConnectionTimeout |
Specifies the amount of time, in milliseconds, that the consumer attempts to establish a connection before it times out. The default is
30000 .
0 specifies that the consumer will continue to send the request indefinitely.
|
ReceiveTimeout |
Specifies the amount of time, in milliseconds, that the consumer will wait for a response before it times out. The default is
30000 .
0 specifies that the consumer will wait indefinitely.
|
AutoRedirect |
Specifies if the consumer will automatically follow a server issued redirection. The default is
false .
|
MaxRetransmits |
Specifies the maximum number of times a consumer will retransmit a request to satisfy a redirect. The default is
-1 which specifies that unlimited retransmissions are allowed.
|
AllowChunking |
Specifies whether the consumer will send requests using chunking. The default is
true which specifies that the consumer will use chunking when sending requests.
Chunking cannot be used if either of the following are true:
In both cases the value of
AllowChunking is ignored and chunking is disallowed.
|
Accept |
Specifies what media types the consumer is prepared to handle. The value is used as the value of the HTTP Accept property. The value of the attribute is specified using multipurpose internet mail extensions (MIME) types.
|
AcceptLanguage |
Specifies what language (for example, American English) the consumer prefers for the purpose of receiving a response. The value is used as the value of the HTTP AcceptLanguage property.
Language tags are regulated by the International Organization for Standards (ISO) and are typically formed by combining a language code, determined by the ISO-639 standard, and country code, determined by the ISO-3166 standard, separated by a hyphen. For example, en-US represents American English.
|
AcceptEncoding |
Specifies what content encodings the consumer is prepared to handle. Content encoding labels are regulated by the Internet Assigned Numbers Authority (IANA). The value is used as the value of the HTTP AcceptEncoding property.
|
ContentType |
Specifies the media type of the data being sent in the body of a message. Media types are specified using multipurpose internet mail extensions (MIME) types. The value is used as the value of the HTTP ContentType property. The default is
text/xml .
For web services, this should be set to
text/xml . If the client is sending HTML form data to a CGI script, this should be set to application/x-www-form-urlencoded . If the HTTP POST request is bound to a fixed payload format (as opposed to SOAP), the content type is typically set to application/octet-stream .
|
Host |
Specifies the Internet host and port number of the resource on which the request is being invoked. The value is used as the value of the HTTP Host property.
This attribute is typically not required. It is only required by certain DNS scenarios or application designs. For example, it indicates what host the client prefers for clusters (that is, for virtual servers mapping to the same Internet protocol (IP) address).
|
Connection |
Specifies whether a particular connection is to be kept open or closed after each request/response dialog. There are two valid values:
|
CacheControl |
Specifies directives about the behavior that must be adhered to by caches involved in the chain comprising a request from a consumer to a service provider. See the section called “Consumer Cache Control Directives”.
|
Cookie |
Specifies a static cookie to be sent with all requests.
|
BrowserType |
Specifies information about the browser from which the request originates. In the HTTP specification from the World Wide Web consortium (W3C) this is also known as the user-agent. Some servers optimize based on the client that is sending the request.
|
Referer |
Specifies the URL of the resource that directed the consumer to make requests on a particular service. The value is used as the value of the HTTP Referer property.
This HTTP property is used when a request is the result of a browser user clicking on a hyperlink rather than typing a URL. This can allow the server to optimize processing based upon previous task flow, and to generate lists of back-links to resources for the purposes of logging, optimized caching, tracing of obsolete or mistyped links, and so on. However, it is typically not used in web services applications.
If the
AutoRedirect attribute is set to true and the request is redirected, any value specified in the Referer attribute is overridden. The value of the HTTP Referer property is set to the URL of the service that redirected the consumer’s original request.
|
DecoupledEndpoint |
Specifies the URL of a decoupled endpoint for the receipt of responses over a separate provider->consumer connection. For more information on using decoupled endpoints see, Section 25.4, “Using the HTTP Transport in Decoupled Mode”.
You must configure both the consumer endpoint and the service provider endpoint to use WS-Addressing for the decoupled endpoint to work.
|
ProxyServer |
Specifies the URL of the proxy server through which requests are routed.
|
ProxyServerPort |
Specifies the port number of the proxy server through which requests are routed.
|
ProxyServerType |
Specifies the type of proxy server used to route requests. Valid values are:
|
Consumer Cache Control Directives
http-conf:client
Cache Control Directives” lists the cache control directives supported by an HTTP consumer.
Table 25.2. http-conf:client
Cache Control Directives
Directive | Behavior |
---|---|
no-cache |
Caches cannot use a particular response to satisfy subsequent requests without first revalidating that response with the server. If specific response header fields are specified with this value, the restriction applies only to those header fields within the response. If no response header fields are specified, the restriction applies to the entire response.
|
no-store |
Caches must not store either any part of a response or any part of the request that invoked it.
|
max-age |
The consumer can accept a response whose age is no greater than the specified time in seconds.
|
max-stale |
The consumer can accept a response that has exceeded its expiration time. If a value is assigned to max-stale, it represents the number of seconds beyond the expiration time of a response up to which the consumer can still accept that response. If no value is assigned, the consumer can accept a stale response of any age.
|
min-fresh |
The consumer wants a response that is still fresh for at least the specified number of seconds indicated.
|
no-transform |
Caches must not modify media type or location of the content in a response between a provider and a consumer.
|
only-if-cached |
Caches should return only responses that are currently stored in the cache, and not responses that need to be reloaded or revalidated.
|
cache-extension |
Specifies additional extensions to the other cache directives. Extensions can be informational or behavioral. An extended directive is specified in the context of a standard directive, so that applications not understanding the extended directive can adhere to the behavior mandated by the standard directive.
|
Example
Example 25.5. WSDL to Configure an HTTP Consumer Endpoint
<service ... > <port ... > <soap:address ... /> <http-conf:client CacheControl="no-cache" /> </port> </service>
25.3. Provider Configuration
Namespace
http-conf
. To use the HTTP configuration elements you must add the line shown in Example 25.6, “HTTP Provider WSDL Element's Namespace” to the definitions
element of your endpoint's WSDL document.
Example 25.6. HTTP Provider WSDL Element's Namespace
<definitions ... xmlns:http-conf="http://cxf.apache.org/transports/http/configuration"
Configuring the endpoint
http-conf:server
element is used to specify the connection properties of an HTTP service provider in a WSDL document. The http-conf:server
element is a child of the WSDL port
element. The attributes are described in Table 25.3, “HTTP Service Provider Configuration Attributes”.
Table 25.3. HTTP Service Provider Configuration Attributes
Attribute | Description |
---|---|
ReceiveTimeout |
Sets the length of time, in milliseconds, the service provider attempts to receive a request before the connection times out. The default is
30000 .
0 specifies that the provider will not timeout.
|
SuppressClientSendErrors |
Specifies whether exceptions are to be thrown when an error is encountered on receiving a request. The default is
false ; exceptions are thrown on encountering errors.
|
SuppressClientReceiveErrors |
Specifies whether exceptions are to be thrown when an error is encountered on sending a response to a consumer. The default is
false ; exceptions are thrown on encountering errors.
|
HonorKeepAlive |
Specifies whether the service provider honors requests for a connection to remain open after a response has been sent. The default is
false ; keep-alive requests are ignored.
|
RedirectURL |
Specifies the URL to which the client request should be redirected if the URL specified in the client request is no longer appropriate for the requested resource. In this case, if a status code is not automatically set in the first line of the server response, the status code is set to
302 and the status description is set to Object Moved . The value is used as the value of the HTTP RedirectURL property.
|
CacheControl |
Specifies directives about the behavior that must be adhered to by caches involved in the chain comprising a response from a service provider to a consumer. See the section called “Service Provider Cache Control Directives”.
|
ContentLocation |
Sets the URL where the resource being sent in a response is located.
|
ContentType |
Specifies the media type of the information being sent in a response. Media types are specified using multipurpose internet mail extensions (MIME) types. The value is used as the value of the HTTP ContentType location.
|
ContentEncoding |
Specifies any additional content encodings that have been applied to the information being sent by the service provider. Content encoding labels are regulated by the Internet Assigned Numbers Authority (IANA). Possible content encoding values include
zip , gzip , compress , deflate , and identity . This value is used as the value of the HTTP ContentEncoding property.
The primary use of content encodings is to allow documents to be compressed using some encoding mechanism, such as zip or gzip. Apache CXF performs no validation on content codings. It is the user’s responsibility to ensure that a specified content coding is supported at application level.
|
ServerType |
Specifies what type of server is sending the response. Values take the form
program-name/version ; for example, Apache/1.2.5 .
|
Service Provider Cache Control Directives
http-conf:server
Cache Control Directives” lists the cache control directives supported by an HTTP service provider.
Table 25.4. http-conf:server
Cache Control Directives
Directive | Behavior |
---|---|
no-cache |
Caches cannot use a particular response to satisfy subsequent requests without first revalidating that response with the server. If specific response header fields are specified with this value, the restriction applies only to those header fields within the response. If no response header fields are specified, the restriction applies to the entire response.
|
public |
Any cache can store the response.
|
private |
Public (shared) caches cannot store the response because the response is intended for a single user. If specific response header fields are specified with this value, the restriction applies only to those header fields within the response. If no response header fields are specified, the restriction applies to the entire response.
|
no-store |
Caches must not store any part of the response or any part of the request that invoked it.
|
no-transform |
Caches must not modify the media type or location of the content in a response between a server and a client.
|
must-revalidate |
Caches must revalidate expired entries that relate to a response before that entry can be used in a subsequent response.
|
proxy-revalidate |
Does the same as must-revalidate, except that it can only be enforced on shared caches and is ignored by private unshared caches. When using this directive, the public cache directive must also be used.
|
max-age |
Clients can accept a response whose age is no greater that the specified number of seconds.
|
s-max-age |
Does the same as max-age, except that it can only be enforced on shared caches and is ignored by private unshared caches. The age specified by s-max-age overrides the age specified by max-age. When using this directive, the proxy-revalidate directive must also be used.
|
cache-extension |
Specifies additional extensions to the other cache directives. Extensions can be informational or behavioral. An extended directive is specified in the context of a standard directive, so that applications not understanding the extended directive can adhere to the behavior mandated by the standard directive.
|
Example
Example 25.7. WSDL to Configure an HTTP Service Provider Endpoint
<service ... > <port ... > <soap:address ... /> <http-conf:server CacheControl="no-cache" /> </port> </service>
25.4. Using the HTTP Transport in Decoupled Mode
Overview
200
.
202 Accepted
response to the consumer over the back-channel of the HTTP connection on which the request was received. It then processes the request and sends the response back to the consumer using a new decoupled server->client HTTP connection. The consumer runtime receives the incoming response and correlates it with the appropriate request before returning to the application code.
Configuring decoupled interactions
- Configure the consumer to use WS-Addressing.
- Configure the consumer to use a decoupled endpoint.
- Configure any service providers that the consumer interacts with to use WS-Addressing.
Configuring an endpoint to use WS-Addressing
- Adding the
wswa:UsingAddressing
element to the endpoint's WSDLport
element as shown in Example 25.8, “Activating WS-Addressing using WSDL”.Example 25.8. Activating WS-Addressing using WSDL
... <service name="WidgetSOAPService"> <port name="WidgetSOAPPort" binding="tns:WidgetSOAPBinding"> <soap:address="http://widgetvendor.net/widgetSeller" /> <wswa:UsingAddressing xmlns:wswa="http://www.w3.org/2005/02/addressing/wsdl"/> </port> </service> ...
- Adding the WS-Addressing policy to the endpoint's WSDL
port
element as shown in Example 25.9, “Activating WS-Addressing using a Policy”.Example 25.9. Activating WS-Addressing using a Policy
... <service name="WidgetSOAPService"> <port name="WidgetSOAPPort" binding="tns:WidgetSOAPBinding"> <soap:address="http://widgetvendor.net/widgetSeller" /> <wsp:Policy xmlns:wsp="http://www.w3.org/2006/07/ws-policy"> <wsam:Addressing xmlns:wsam="http://www.w3.org/2007/02/addressing/metadata"> <wsp:Policy/> </wsam:Addressing> </wsp:Policy> </port> </service> ...
wswa:UsingAddressing
WSDL element.
Configuring the consumer
DecoupledEndpoint
attribute of the http-conf:conduit
element.
Example 25.10. Configuring a Consumer to Use a Decoupled HTTP Endpoint
<beans xmlns="http://www.springframework.org/schema/beans" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:http="http://cxf.apache.org/transports/http/configuration" xsi:schemaLocation="http://cxf.apache.org/transports/http/configuration http://cxf.apache.org/schemas/configuration/http-conf.xsd http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd"> <http:conduit name="{http://widgetvendor.net/services}WidgetSOAPPort.http-conduit"> <http:client DecoupledEndpoint="http://widgetvendor.net:9999/decoupled_endpoint" /> </http:conduit> </beans>
How messages are processed
Figure 25.1. Message Flow in for a Decoupled HTTP Transport
- The consumer implementation invokes an operation and a request message is generated.
- The WS-Addressing layer adds the WS-A headers to the message.When a decoupled endpoint is specified in the consumer's configuration, the address of the decoupled endpoint is placed in the WS-A ReplyTo header.
- The message is sent to the service provider.
- The service provider receives the message.
- The request message from the consumer is dispatched to the provider's WS-A layer.
- Because the WS-A ReplyTo header is not set to anonymous, the provider sends back a message with the HTTP status code set to
202
, acknowledging that the request has been received. - The HTTP layer sends a
202 Accepted
message back to the consumer using the original connection's back-channel. - The consumer receives the
202 Accepted
reply on the back-channel of the HTTP connection used to send the original message.When the consumer receives the202 Accepted
reply, the HTTP connection closes. - The request is passed to the service provider's implementation where the request is processed.
- When the response is ready, it is dispatched to the WS-A layer.
- The WS-A layer adds the WS-Addressing headers to the response message.
- The HTTP transport sends the response to the consumer's decoupled endpoint.
- The consumer's decoupled endpoint receives the response from the service provider.
- The response is dispatched to the consumer's WS-A layer where it is correlated to the proper request using the WS-A RelatesTo header.
- The correlated response is returned to the client implementation and the invoking call is unblocked.
Chapter 26. Using JMS
Abstract
26.1. Using SOAP/JMS
26.1.1. Basic configuration
Overview
- Specify that the transport type is SOAP/JMS.
- Specify the target destination using a JMS URI.
- Optionally, configure the JNDI connection.
- Optionally, add additional JMS configuration.
Specifying the JMS transport type
soap:binding
element's transport
attribute to http://www.w3.org/2010/soapjms/
. Example 26.1, “SOAP over JMS binding specification” shows a WSDL binding that uses SOAP/JMS.
Example 26.1. SOAP over JMS binding specification
<wsdl:binding ... > <soap:binding style="document" transport="http://www.w3.org/2010/soapjms/" /> ... </wsdl:binding>
Specifying the target destination
soap:address
element and attribute as a SOAP/HTTP endpoint. The difference is the address specification. JMS endpoints use a JMS URI as defined in the URI Scheme for JMS 1.0. Example 26.2, “JMS URI syntax” shows the syntax for a JMS URI.
Example 26.2. JMS URI syntax
jms:variant:destination?options
Table 26.1. JMS URI variants
Variant | Description |
---|---|
jndi | Specifies that the destination is a JNDI name for the target destination. When using this variant, you must provide the configuration for accessing the JNDI provider. |
topic | Specifies that the destination is the name of the topic to be used as the target destination. The string provided is passed into Session.createTopic() to create a representation of the destination. |
queue | Specifies that the destination is the name of the queue to be used as the target destination. The string provided is passed into Session.createQueue() to create a representation of the destination. |
Example 26.3. SOAP/JMS endpoint address
<wsdl:port ... > ... <soap:address location="jms:jndi:dynamicQueues/test.cxf.jmstransport.queue" /> </wsdl:port>
Configuring JNDI and the JMS transport
26.1.2. JMS URIs
Overview
Syntax
?
). Multiple options are separated by an ampersand(&
). Example 26.4, “Syntax for JMS URI options” shows the syntax for using multiple options in a JMS URI.
Example 26.4. Syntax for JMS URI options
jmsAddress?option1=value1&option2=value2&...optionN=valueN
JMS properties
Table 26.2. JMS properties settable as URI options
Property | Default | Description |
---|---|---|
deliveryMode | PERSISTENT | Specifies whether to use JMS PERSISTENT or NON_PERSISTENT message semantics. In the case of PERSISTENT delivery mode, the JMS broker stores messages in persistent storage before acknowledging them; whereas NON_PERSISTENT messages are kept in memory only. |
replyToName |
Explicitly specifies the reply destination to appear in the
JMSReplyTo header. Setting this property is recommended for applications that have request-reply semantics because the JMS provider will assign a temporary reply queue if one is not explicitly set.
The value of this property has an interpretation that depends on the variant specified in the JMS URI:
| |
priority | 4 | Specifies the JMS message priority, which ranges from 0 (lowest) to 9 (highest). |
timeToLive | 0 | Time (in milliseconds) after which the message will be discarded by the JMS provider. A value of 0 represents an infinite lifetime (the default). |
JNDI properties
Table 26.3. JNDI properties settable as URI options
Property | Description |
---|---|
jndiConnectionFactoryName | Specifies the JNDI name of the JMS connection factory. |
jndiInitialContextFactory | Specifies the fully qualified Java class name of the JNDI provider (which must be of javax.jms.InitialContextFactory type). Equivalent to setting the java.naming.factory.initial Java system property. |
jndiURL | Specifies the URL that initializes the JNDI provider. Equivalent to setting the java.naming.provider.url Java system property. |
Additional JNDI properties
java.naming.factory.initial
and java.naming.provider.url
, are standard properties, which are required to initialize any JNDI provider. Sometimes, however, a JNDI provider might support custom properties in addition to the standard ones. In this case, you can set an arbitrary JNDI property by setting a URI option of the form jndi-PropertyName
.
java.naming.factory.control
, in a JMS URI as shown in Example 26.5, “Setting a JNDI property in a JMS URI”.
Example 26.5. Setting a JNDI property in a JMS URI
jms:queue:FOO.BAR?jndi-java.naming.factory.control=com.sun.jndi.ldap.ResponseControlFactory
Example
test.cxf.jmstransport.queue
, use the URI shown in Example 26.6, “JMS URI that configures a JNDI connection”.
Example 26.6. JMS URI that configures a JNDI connection
jms:jndi:dynamicQueues/test.cxf.jmstransport.queue ?jndiInitialContextFactory=org.apache.activemq.jndi.ActiveMQInitialContextFactory &jndiConnectionFactoryName=ConnectionFactory &jndiURL=tcp://localhost:61616
26.1.3. WSDL extensions
Overview
InitialContext
, which can then be used to look up JMS destinations. You can also set some properties that affect the behavior of the JMS transport layer.
SOAP/JMS namespace
http://www.w3.org/2010/soapjms/
namespace. To use them in your WSDL contracts add the following setting to the wsdl:definitions
element:
<wsdl:definitions ... xmlns:soapjms="http://www.w3.org/2010/soapjms/" ... >
WSDL extension elements
Table 26.4. SOAP/JMS WSDL extension elements
Element | Default | Description |
---|---|---|
soapjms:jndiInitialContextFactory | Specifies the fully qualified Java class name of the JNDI provider. Equivalent to setting the java.naming.factory.initial Java system property. | |
soapjms:jndiURL | Specifies the URL that initializes the JNDI provider. Equivalent to setting the java.naming.provider.url Java system property. | |
soapjms:jndiContextParameter | Enables you to specify an additional property for creating the JNDI InitialContext . Use the name and value attributes to specify the property. | |
soapjms:jndiConnectionFactoryName | Specifies the JNDI name of the JMS connection factory. | |
soapjms:deliveryMode | PERSISTENT | Specifies whether to use JMS PERSISTENT or NON_PERSISTENT message semantics. In the case of PERSISTENT delivery mode, the JMS broker stores messages in persistent storage before acknowledging them; whereas NON_PERSISTENT messages are kept in memory only. |
soapjms:replyToName |
Explicitly specifies the reply destination to appear in the
JMSReplyTo header. Setting this property is recommended for SOAP invocations that have request-reply semantics. If this property is not set the JMS provider allocates a temporary queue with an automatically generated name.
The value of this property has an interpretation that depends on the variant specified in the JMS URI, as follows:
| |
soapjms:priority | 4 | Specifies the JMS message priority, which ranges from 0 (lowest) to 9 (highest). |
soapjms:timeToLive | 0 | Time, in milliseconds, after which the message will be discarded by the JMS provider. A value of 0 represents an infinite lifetime. |
Configuration scopes
wsdl:binding
element, the wsdl:service
element, or the wsdl:port
element. The parent of the SOAP/JMS elements determine which of the following scopes the configuration is placed into.
- Binding scope
- You can configure the JMS transport at the binding scope by placing extension elements inside the
wsdl:binding
element. Elements in this scope define the default configuration for all endpoints that use this binding. Any settings in the binding scope can be overridden at the service scope or the port scope. - Service scope
- You can configure the JMS transport at the service scope by placing extension elements inside a
wsdl:service
element. Elements in this scope define the default configuration for all endpoints in this service. Any settings in the service scope can be overridden at the port scope. - Port scope
- You can configure the JMS transport at the port scope by placing extension elements inside a
wsdl:port
element. Elements in the port scope define the configuration for this port. They override any defaults defined at the service scope or at the binding scope.
Example
Example 26.7. WSDL contract with SOAP/JMS configuration
<wsd;definitions ... 1 xmlns:soapjms="http://www.w3.org/2010/soapjms/" ... > ... <wsdl:binding name="JMSGreeterPortBinding" type="tns:JMSGreeterPortType"> ... 2 <soapjms:jndiInitialContextFactory> org.apache.activemq.jndi.ActiveMQInitialContextFactory </soapjms:jndiInitialContextFactory> <soapjms:jndiURL>tcp://localhost:61616</soapjms:jndiURL> <soapjms:jndiConnectionFactoryName> ConnectionFactory </soapjms:jndiConnectionFactoryName> ... </wsdl:binding> ... <wsdl:service name="JMSGreeterService"> ... 3 <soapjms:deliveryMode>NON_PERSISTENT</soapjms:deliveryMode> <soapjms:timeToLive>60000</soapjms:timeToLive> ... <wsdl:port binding="tns:JMSGreeterPortBinding" name="GreeterPort"> 4 <soap:address location="jms:jndi:dynamicQueues/test.cxf.jmstransport.queue" /> 5 <soapjms:replyToName> dynamicQueues/greeterReply.queue </soapjms:replyToName> ... </wsdl:port> ... </wsdl:service> ... </wsdl:definitions>
- 1
- Declare the namespace for the SOAP/JMS extensions.
- 2
- Configure the JNDI connections in the binding scope.
- 3
- Configure the JMS delivery style to non-persistent and each message to live for one minute.
- 4
- Specify the target destination.
- 5
- Configure the JMS transport so that reply messages are delivered on the
greeterReply.queue
queue.
26.2. Using WSDL to configure JMS
Example 26.8. JMS WSDL extension namespace
xmlns:jms="http://cxf.apache.org/transports/jms"
26.2.1. Basic JMS configuration
Overview
jms:address
element and its child, the jms:JMSNamingProperties
element. The jms:address
element’s attributes specify the information needed to identify the JMS broker and the destination. The jms:JMSNamingProperties
element specifies the Java properties used to connect to the JNDI service.
Specifying the JMS address
jms:address
element as the child of your service’s port
element. The jms:address
element used in WSDL is identical to the one used in the configuration file. Its attributes are listed in Table 26.5, “JMS endpoint attributes”.
Table 26.5. JMS endpoint attributes
Attribute | Description |
---|---|
destinationStyle | Specifies if the JMS destination is a JMS queue or a JMS topic. |
jndiConnectionFactoryName | Specifies the JNDI name bound to the JMS connection factory to use when connecting to the JMS destination. |
jmsDestinationName | Specifies the JMS name of the JMS destination to which requests are sent. |
jmsReplyDestinationName | Specifies the JMS name of the JMS destinations where replies are sent. This attribute allows you to use a user defined destination for replies. For more details see Section 26.3, “Using a Named Reply Destination”. |
jndiDestinationName | Specifies the JNDI name bound to the JMS destination to which requests are sent. |
jndiReplyDestinationName | Specifies the JNDI name bound to the JMS destinations where replies are sent. This attribute allows you to use a user defined destination for replies. For more details see Section 26.3, “Using a Named Reply Destination”. |
connectionUserName | Specifies the user name to use when connecting to a JMS broker. |
connectionPassword | Specifies the password to use when connecting to a JMS broker. |
jms:address
WSDL element uses a jms:JMSNamingProperties
child element to specify additional information needed to connect to a JNDI provider.
Specifying JNDI properties
jms:address
element has a child element, jms:JMSNamingProperties
, that allows you to specify the values used to populate the properties used when connecting to the JNDI provider. The jms:JMSNamingProperties
element has two attributes: name
and value
. name
specifies the name of the property to set. value
attribute specifies the value for the specified property. jms:JMSNamingProperties
element can also be used for specification of provider specific properties.
java.naming.factory.initial
java.naming.provider.url
java.naming.factory.object
java.naming.factory.state
java.naming.factory.url.pkgs
java.naming.dns.url
java.naming.authoritative
java.naming.batchsize
java.naming.referral
java.naming.security.protocol
java.naming.security.authentication
java.naming.security.principal
java.naming.security.credentials
java.naming.language
java.naming.applet
Example
port
specification.
Example 26.9. JMS WSDL port specification
<service name="JMSService"> <port binding="tns:Greeter_SOAPBinding" name="SoapPort"> <jms:address jndiConnectionFactoryName="ConnectionFactory" jndiDestinationName="dynamicQueues/test.Celtix.jmstransport" > <jms:JMSNamingProperty name="java.naming.factory.initial" value="org.activemq.jndi.ActiveMQInitialContextFactory" /> <jms:JMSNamingProperty name="java.naming.provider.url" value="tcp://localhost:61616" /> </jms:address> </port> </service>
26.2.2. JMS client configuration
Overview
ByteMessage
or a JMS TextMessage
.
ByteMessage
the consumer endpoint uses a byte[] as the method for storing data into and retrieving data from the JMS message body. When messages are sent, the message data, including any formating information, is packaged into a byte[] and placed into the message body before it is placed on the wire. When messages are received, the consumer endpoint will attempt to unmarshall the data stored in the message body as if it were packed in a byte[].
TextMessage
, the consumer endpoint uses a string as the method for storing and retrieving data from the message body. When messages are sent, the message information, including any format-specific information, is converted into a string and placed into the JMS message body. When messages are received the consumer endpoint will attempt to unmarshall the data stored in the JMS message body as if it were packed into a string.
TextMessage
, the receiving JMS application will get a text message containing all of the SOAP envelope information.
Specifying the message type
jms:client
element. The jms:client
element is a child of the WSDL port
element and has one attribute:
Example
Example 26.10. WSDL for a JMS consumer endpoint
<service name="JMSService"> <port binding="tns:Greeter_SOAPBinding" name="SoapPort"> <jms:address jndiConnectionFactoryName="ConnectionFactory" jndiDestinationName="dynamicQueues/test.Celtix.jmstransport" > <jms:JMSNamingProperty name="java.naming.factory.initial" value="org.activemq.jndi.ActiveMQInitialContextFactory" /> <jms:JMSNamingProperty name="java.naming.provider.url" value="tcp://localhost:61616" /> </jms:address> <jms:client messageType="binary" /> </port> </service>
26.2.3. JMS provider configuration
Overview
- how messages are correlated
- the use of durable subscriptions
- if the service uses local JMS transactions
- the message selectors used by the endpoint
Specifying the configuration
jms:server
element. The jms:server
element is a child of the WSDL wsdl:port
element and has the following attributes:
Table 26.7. JMS provider endpoint WSDL extensions
Attribute | Description |
---|---|
useMessageIDAsCorrealationID | Specifies whether JMS will use the message ID to correlate messages. The default is false . |
durableSubscriberName | Specifies the name used to register a durable subscription. |
messageSelector | Specifies the string value of a message selector to use. For more information on the syntax used to specify message selectors, see the JMS 1.1 specification. |
transactional | Specifies whether the local JMS broker will create transactions around message processing. The default is false . [a] |
Example
Example 26.11. WSDL for a JMS provider endpoint
<service name="JMSService"> <port binding="tns:Greeter_SOAPBinding" name="SoapPort"> <jms:address jndiConnectionFactoryName="ConnectionFactory" jndiDestinationName="dynamicQueues/test.Celtix.jmstransport" > <jms:JMSNamingProperty name="java.naming.factory.initial" value="org.activemq.jndi.ActiveMQInitialContextFactory" /> <jms:JMSNamingProperty name="java.naming.provider.url" value="tcp://localhost:61616" /> </jms:address> <jms:server messageSelector="cxf_message_selector" useMessageIDAsCorrelationID="true" transactional="true" durableSubscriberName="cxf_subscriber" /> </port> </service>
26.3. Using a Named Reply Destination
Overview
Setting the reply destination name
jmsReplyDestinationName
attribute or the jndiReplyDestinationName
attribute in the endpoint's JMS configuration. A client endpoint will listen for replies on the specified destination and it will specify the value of the attribute in the ReplyTo
field of all outgoing requests. A service endpoint will use the value of the jndiReplyDestinationName
attribute as the location for placing replies if there is no destination specified in the request’s ReplyTo
field.
Example
Example 26.12. JMS Consumer Specification Using a Named Reply Queue
<jms:conduit name="{http://cxf.apache.org/jms_endpt}HelloWorldJMSPort.jms-conduit">
<jms:address destinationStyle="queue"
jndiConnectionFactoryName="myConnectionFactory"
jndiDestinationName="myDestination"
jndiReplyDestinationName="myReplyDestination" >
<jms:JMSNamingProperty name="java.naming.factory.initial"
value="org.apache.cxf.transport.jms.MyInitialContextFactory" />
<jms:JMSNamingProperty name="java.naming.provider.url"
value="tcp://localhost:61616" />
</jms:address>
</jms:conduit>
Chapter 27. Introduction to the Apache CXF Binding Component
Abstract
Contents of a file component service unit
xbean.xml
- The
xbean.xml
file contains the XML configuration for the endpoint defined by the service unit. The contents of this file are the focus of this guide.NoteThe service unit can define more than one endpoint. - WSDL file
- The WSDL file defines the endpoint the interface exposes.
- Spring configuration file
- The Spring configuration file contains configuration for the Apache CXF runtime.
meta-inf/jbi.xml
- The
jbi.xml
file is the JBI descriptor for the service unit. Example 27.1, “JBI Descriptor for a Apache CXF Binding Component Service Unit” shows a JBI descriptor for a Apache CXF binding component service unit.Example 27.1. JBI Descriptor for a Apache CXF Binding Component Service Unit
<jbi xmlns="http://java.sun.com/xml/ns/jbi" version="1.0"> <services binding-component="false" /> </jbi>
OSGi Packaging
- you will need to include an OSGi bundle manifest in the
META-INF
folder of the bundle. - You need to add the following to your service unit's configuration file:
<bean class="org.apache.servicemix.common.osgi.EndpointExporter" />
Namespace
http://servicemix.apache.org/cxfbc/1.0
namespace. You will need to add a namespace declaration similar to the one in Example 27.2, “Namespace Declaration for Using Apache CXF Binding Component Endpoints” to your xbeans.xml
file's beans
element.
Example 27.2. Namespace Declaration for Using Apache CXF Binding Component Endpoints
<beans ...
xmlns:cxfbc="http://servicemix.apache.org/cxfbc/1.0"
... >
...
</beans>
beans
element's xsi:schemaLocation
as shown in Example 27.3, “Schema Location for Using Apache CXF Binding Component Endpoints”.
Example 27.3. Schema Location for Using Apache CXF Binding Component Endpoints
<beans ... xsi:schemaLocation="... http://servicemix.apache.org/cxfbc/1.0 http://servicemix.apache.org/cxfbc/1.0/servicemix-cxfbc.xsd ..."> ... </beans>
Chapter 28. Consumer Endpoints
Abstract
Overview
Figure 28.1. Consumer Endpoint
Procedure
- Add a
consumer
element to yourxbean.xml
file. - Add a
wsdl
attribute to theconsumer
element. - If your WSDL defines more than one service, you will need to specify a value for the
service
attribute. - If the service you choose defines more than one endpoint, you will need to specify a value for the
endpoint
attribute. - Specify the details for the target of the requests received by the endpoint.
- If your endpoint is going to be receiving binary attachments set its
mtomEnabled
attribute totrue
. - If your endpoint does not need to process the JBI wrapper set its
useJbiWrapper
attribute tofalse
. - If you are using any of the advanced features, such as WS-Addressing or WS-Policy, specify a value for the
busCfg
attribute.See ???.
Specifying the WSDL
wsdl
attribute is the only required attribute to configure a consumer endpoint. It specifies the location of the WSDL document that defines the endpoint being exposed. The path used is relative to the top-level of the exploded service unit.
Example 28.1. Minimal Consumer Endpoint Configuration
<beans xmlns:cxfbc="http://servicemix.apache.org/cxfbc/1.0" ... > ... <cxfbc:consumer wsdl="/wsdl/widget.wsdl" /> ... </beans>
Specifying the endpoint details
service
element you will need to specify a value for the consumer's service
attribute. The value of the consumer's service
attribute is the QName of the WSDL service
element that defines the desired service in the WSDL document. For example, if you wanted your endpoint to use the WidgetSalesService in the WSDL shown in Example 28.2, “WSDL with Two Services” you would use the configuration shown in Example 28.3, “Consumer Endpoint with a Defined Service Name”.
Example 28.2. WSDL with Two Services
<definitions ... xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" targetNamespace="http://demos.widgetVendor.com" ...> ... <service name="WidgetSalesService"> <port binding="WidgetSalesBinding" name="WidgetSalesPort"> <soap:address location="http://widget.sales.com/index.xml"> </port> </service> <service name="WidgetInventoryService"> <port binding="WidgetInventoryBinding" name="WidgetInventoryPort"> <soap:address location="http://widget.inventory.com/index.xml"> </port> </service> ... <definitions>
Example 28.3. Consumer Endpoint with a Defined Service Name
<beans xmlns:cxfbc="http://servicemix.apache.org/cxfbc/1.0"
xmlns:widgets="http://demos.widgetVendor.com"
... >
...
<cxfbc:consumer wsdl="/wsdl/widget.wsdl"
service="widgets:WidgetSalesService" />
...
</beans>
endpoint
attribute. The value of the endpoint
attribute corresponds to the value of the WSDL port
element's name
attribute. For example, if you wanted your endpoint to use the WidgetEasternSalesPort in the WSDL shown in Example 28.4, “Service with Two Endpoints” you would use the configuration shown in Example 28.5, “Consumer Endpoint with a Defined Endpoint Name”.
Example 28.4. Service with Two Endpoints
<definitions ... xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" targetNamespace="http://demos.widgetVendor.com" ...> ... <service name="WidgetSalesService"> <port binding="WidgetSalesBinding" name="WidgetWesternSalesPort"> <soap:address location="http://widget.sales.com/index.xml"> </port> <port binding="WidgetSalesBinding" name="WidgetEasternSalesPort"> <jms:address jndiConnectionFactoryName="ConnectionFactory" jndiDestinationName="dynamicQueues/test.Celtix.jmstransport" > <jms:JMSNamingProperty name="java.naming.factory.initial" value="org.activemq.jndi.ActiveMQInitialContextFactory" /> <jms:JMSNamingProperty name="java.naming.provider.url" value="tcp://localhost:61616" /> </jms:address> </port> </service> ... <definitions>
Example 28.5. Consumer Endpoint with a Defined Endpoint Name
<beans xmlns:cxfbc="http://servicemix.apache.org/cxfbc/1.0"
xmlns:widgets="http://demos.widgetVendor.com"
... >
...
<cxfbc:consumer wsdl="/wsdl/widget.wsdl"
endpoint="WidgetEasternSalesService" />
...
</beans>
Specifying the target endpoint
- If you explicitly specify an endpoint using both the
targetService
attribute and thetargetEndpoint
attribute, the ESB will use that endpoint. - If you only specify a value for the
targetService
attribute, the ESB will attempt to find an appropriate endpoint on the specified service. - If you specify an the name of an interface that can accept the message using the
targetInterface
attribute, the ESB will attempt to locate an endpoint that implements the specified interface and direct the messages to it. - If you do not use any of the target attributes, the ESB will use the values used in configuring the endpoint's service name and endpoint name to determine the target endpoint.
Example 28.6. Consumer Endpoint Configuration Specifying a Target Endpoint
<beans xmlns:cxfbc="http://servicemix.apache.org/cxfbc/1.0" xmlns:widgets="http://demos.widgetVendor.com" ... > ... <cxfbc:consumer wsdl="/wsdl/widget.wsdl" targetEndpoint="WidgetSalesTargetPort" targetService="widgets:WidgetSalesTargetService" /> ... </beans>
Chapter 29. Provider Endpoints
Abstract
Overview
Figure 29.1. Provider Endpoint
Procedure
- Add a
provider
element to yourxbean.xml
file. - Add a
wsdl
attribute to theprovider
element. - If your WSDL defines more than one service, you will need to specify a value for the
service
attribute. - If the service you choose defines more than one endpoint, you will need to specify a value for the
endpoint
attribute. - If your endpoint is going to be receiving binary attachments set its
mtomEnabled
attribute totrue
. - If your endpoint does not need to process the JBI wrapper set its
useJbiWrapper
attribute tofalse
. - If you are using any of the advanced features, such as WS-Addressing or WS-Policy, specify a value for the
busCfg
attribute.See ???.
Specifying the WSDL
wsdl
attribute is the only required attribute to configure a provider endpoint. It specifies the location of the WSDL document that defines the endpoint being exposed. The path used is relative to the top-level of the exploded service unit.
Example 29.1. Minimal Provider Endpoint Configuration
<beans xmlns:cxfbc="http://servicemix.apache.org/cxfbc/1.0" ... > ... <cxfbc:provider wsdl="/wsdl/widget.wsdl" /> ... </beans>
Specifying the endpoint details
service
element you will need to specify a value for the provider's service
attribute. The value of the provider's service
attribute is the QName of the WSDL service
element that defines the desired service in the WSDL document. For example, if you wanted your endpoint to use the WidgetInventoryService in the WSDL shown in Example 29.2, “WSDL with Two Services” you would use the configuration shown in Example 29.3, “Provider Endpoint with a Defined Service Name”.
Example 29.2. WSDL with Two Services
<definitions ... xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" targetNamespace="http://demos.widgetVendor.com" ...> ... <service name="WidgetSalesService"> <port binding="WidgetSalesBinding" name="WidgetSalesPort"> <soap:address location="http://widget.sales.com/index.xml"> </port> </service> <service name="WidgetInventoryService"> <port binding="WidgetInventoryBinding" name="WidgetInventoryPort"> <soap:address location="http://widget.inventory.com/index.xml"> </port> </service> ... <definitions>
Example 29.3. Provider Endpoint with a Defined Service Name
<beans xmlns:cxfbc="http://servicemix.apache.org/cxfbc/1.0"
xmlns:widgets="http://demos.widgetVendor.com"
... >
...
<cxfbc:provider wsdl="/wsdl/widget.wsdl"
service="widgets:WidgetInventoryService" />
...
</beans>
endpoint
attribute. The value of the endpoint
attribute corresponds to the value of the WSDL port
element's name
attribute. For example, if you wanted your endpoint to use the WidgetWesternSalesPort in the WSDL shown in Example 29.4, “Service with Two Endpoints” you would use the configuration shown in Example 29.5, “Provider Endpoint with a Defined Endpoint Name”.
Example 29.4. Service with Two Endpoints
<definitions ... xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" targetNamespace="http://demos.widgetVendor.com" ...> ... <service name="WidgetSalesService"> <port binding="WidgetSalesBinding" name="WidgetWesternSalesPort"> <soap:address location="http://widget.sales.com/index.xml"> </port> <port binding="WidgetSalesBinding" name="WidgetEasternSalesPort"> <jms:address jndiConnectionFactoryName="ConnectionFactory" jndiDestinationName="dynamicQueues/test.Celtix.jmstransport" > <jms:JMSNamingProperty name="java.naming.factory.initial" value="org.activemq.jndi.ActiveMQInitialContextFactory" /> <jms:JMSNamingProperty name="java.naming.provider.url" value="tcp://localhost:61616" /> </jms:address> </port> </service> ... <definitions>
Example 29.5. Provider Endpoint with a Defined Endpoint Name
<beans xmlns:cxfbc="http://servicemix.apache.org/cxfbc/1.0"
xmlns:widgets="http://demos.widgetVendor.com"
... >
...
<cxfbc:provider wsdl="/wsdl/widget.wsdl"
endpoint="WidgetWesternSalesService" />
...
</beans>
Chapter 30. Using MTOM to Process Binary Content
Abstract
Overview
Configuring an endpoint to support MTOM
mtomEnabled
attribute to true.
Example 30.1. Configuring an Endpoint to Use MTOM
<beans xmlns:cxfbc="http://servicemix.apache.org/cxfbc/1.0"
...>
<cxfbc:consumer wsdl="/wsdl/widget.wsdl"
mtomEnabled="true" />
...
</beans>
Chapter 31. Working with the JBI Wrapper
Abstract
Overview
Turning of JBI wrapper processing
useJbiWrapper
attribute to false
. This instructs the endpoint to disable the processing of the JBI wrapper. If the endpoint does receive a message that uses the JBI wrapper, it will fail to process the message and generate an error.
Example
Example 31.1. Configuring a Consumer to Not Use the JBI Wrapper
<beans xmlns:cxfbc="http://servicemix.apache.org/cxfbc/1.0"
... >
...
<cxfbc:consumer wsdl="/wsdl/widget.wsdl"
useJbiWrapper="false" />
...
</beans>
Chapter 32. Using Message Interceptors
Abstract
Overview
Configuring an endpoint's interceptor chain
- in interceptors
- On consumer endpoints the in interceptors process messages when they are received from the external endpoint.On provider endpoints the in interceptors process messages when they are received from the NMR.
- in fault interceptors
- The in fault interceptors process fault messages that are generated before the service implementation gets called.
- out interceptors
- On consumer endpoints the out interceptors process messages as they pass from the service implementation to the external endpoint.On provider endpoints the out interceptors process messages as they pass from the service implementation to the NMR.
- out fault interceptors
- The out fault interceptors process fault messages that are generated by the service implementation or by an out interceptor.
consumer
element or provider
element. Table 32.1, “Elements Used to Configure an Endpoint's Interceptor Chain” lists the elements used to configure an endpoint's interceptor chain.
Table 32.1. Elements Used to Configure an Endpoint's Interceptor Chain
Example 32.1. Configuring an Interceptor Chain
<cxfbc:consumer ...> ... <cxfbc:inInterceptors> <bean class="org.apache.cxf.interceptor.LoggingInInterceptor" /> </cxfbc:inInterceptors> <cxfbc:outInterceptors> <bean class="org.apache.cxf.interceptor.LoggingOutInterceptor" /> </cxfbc:outInterceptors> <cxfbc:inFaultInterceptors> <bean class="org.apache.cxf.interceptor.LoggingInInterceptor" /> </cxfbc:inFaultInterceptors> <cxfbc:outFaultInterceptors> <bean class="org.apache.cxf.interceptor.LoggingOutInterceptor" /> </cxfbc:outFaultInterceptors> </cxfbc:consumer>
Implementing an interceptor
org.apache.cxf.phase.AbstractPhaseInterceptor
class or one of its sub-classes. Extending AbstractPhaseInterceptor
provides you with access to the generic message handling APIs used by Apache CXF. Extending one of the sub-classes provides you with more specific APIs. For example, extending the AbstractSoapInterceptor
class allows your interceptor to work directly with the SOAP APIs.
More information
Chapter 33. Configuring the Endpoints to Load Apache CXF Runtime Configuration
Abstract
busCfg
attribute to configure the endpoint to load Apache CXF runtime configuration. Its value points to a Apache CXF configuration file.
Specifying the configuration to load
busCfg
attribute. Both the provider
element and the consumer
element accept this attribute. The attribute's value is the path to a file containing configuration information used by the Apache CXF runtime. This path is relative to the location of the endpoint's xbean.xml
file.
Example
jms-config.xml
.
Example 33.1. Provider Endpoint that Loads Apache CXF Runtime Configuration
<beans xmlns:cxfbc="http://servicemix.apache.org/cxfbc/1.0"
xmlns:greeter="http://cxf.apache.org/jms_greeter"
xmlns:test="http://test">
<cxfbc:provider wsdl="classpath:jms_greeter.wsdl"
service="greeter:JMSGreeterService"
endpoint="GreeterPort"
interfaceName="greeter:JMSGreeterPortType"
useJBIWrapper="false"
busCfg="./jms-config.xml" />
</beans>
Chapter 34. Transport Configuration
34.1. Using the JMS configuration bean
Overview
org.apache.cxf.transport.jms.JMSConfiguration
class. It can be used to either configure endpoint's directly or to configure the JMS conduits and destinations.
Configuration namespace
Example 34.1. Declaring the Spring p-namespace
<beans ... xmlns:p="http://www.springframework.org/schema/p" ... > ... </beans>
Specifying the configuration
org.apache.cxf.transport.jms.JMSConfiguration
. The properties of the bean provide the configuration settings for the transport.
Table 34.1. General JMS Configuration Properties
Property | Default | Description |
---|---|---|
connectionFactory-ref | Specifies a reference to a bean that defines a JMS ConnectionFactory . | |
wrapInSingleConnectionFactory | true | Specifies whether to wrap the ConnectionFactory with a Spring SingleConnectionFactory . Doing so can improve the performance of the JMS transport when the specified connection factory does not pool connections. |
reconnectOnException | false | Specifies whether to create a new connection in the case of an exception. This property is only used when wrapping the connection factory with a Spring SingleConnectionFactory . |
targetDestination | Specifies the JNDI name or provider specific name of a destination. | |
replyDestination | Specifies the JMS name of the JMS destinations where replies are sent. This attribute allows you to use a user defined destination for replies. For more details see Section 26.3, “Using a Named Reply Destination”. | |
destinationResolver | Specifies a reference to a Spring DestinationResolver . This allows you to define how destination names are resolved. By default a DynamicDestinationResolver is used. It resolves destinations using the JMS providers features. If you reference a JndiDestinationResolver you can resolve the destination names using JNDI. | |
transactionManager | Specifies a reference to a Spring transaction manager. This allows the service to participate in JTA Transactions. | |
taskExecutor | Specifies a reference to a Spring TaskExecutor . This is used in listeners to decide how to handle incoming messages. By default the transport uses the Spring SimpleAsyncTaskExecutor . | |
useJms11 | false | Specifies whether JMS 1.1 features are available. |
messageIdEnabled | true | Specifies whether the JMS transport wants the JMS broker to provide message IDs. Setting this to false causes the endpoint to call its message producer's setDisableMessageID() method with a value of true . The JMS broker is then given a hint that it does not need to generate message IDs or add them to the messages from the endpoint. The JMS broker can choose to accept the hint or ignore it. |
messageTimestampEnabled | true | Specifies whether the JMS transport wants the JMS broker to provide message time stamps. Setting this to false causes the endpoint to call its message producer's setDisableMessageTimestamp() method with a value of true . The JMS broker is then given a hint that it does not need to generate time stamps or add them to the messages from the endpoint. The JMS broker can choose to accept the hint or ignore it. |
cacheLevel | 3 | Specifies the level of caching allowed by the listener. Valid values are 0 (CACHE_NONE), 1 (CACHE_CONNECTION), 2 (CACHE_SESSION), 3 (CACHE_CONSUMER), 4 (CACHE_AUTO). |
pubSubNoLocal | false | Specifies whether to receive messages produced from the same connection. |
receiveTimeout | 0 | Specifies, in milliseconds, the amount of time to wait for response messages. 0 means wait indefinitely. |
explicitQosEnabled | false | Specifies whether the QoS settings like priority, persistence, and time to live are explicitly set for each message or if they are allowed to use default values. |
deliveryMode | 1 |
Specifies if a message is persistent. The two values are:
|
priority | 4 | Specifies the message's priority for the messages. JMS priority values can range from 0 to 9. The lowest priority is 0 and the highest priority is 9. |
timeToLive | 0 | Specifies, in milliseconds, the message will be available after it is sent. 0 specifies an infinite time to live. |
sessionTransacted | false | Specifies if JMS transactions are used. |
concurrentConsumers | 1 | Specifies the minimum number of concurrent consumers created by the listener. |
maxConcurrentConsumers | 1 | Specifies the maximum number of concurrent consumers by listener. |
messageSelector | Specifies the string value of the selector. For more information on the syntax used to specify message selectors, see the JMS 1.1 specification. | |
subscriptionDurable | false | Specifies whether the server uses durrable subscriptions. |
durableSubscriptionName | Specifies the string used to register the durable subscription. | |
messageType | text | Specifies how the message data will be packaged as a JMS message. text specifies that the data will be packaged as a TextMessage . binary specifies that the data will be packaged as an ByteMessage . |
pubSubDomain | false | Specifies whether the target destination is a topic. |
jmsProviderTibcoEms | false | Specifies if your JMS provider is Tibco EMS. This causes the principal in the security context to be populated from the JMS_TIBCO_SENDER header. |
useMessageIDAsCorrelationID | false | Specifies whether JMS will use the message ID to correlate messages. If not, the client will set a generated correlation ID. |
bean
element. They are all declared in the Spring p
namespace.
Example 34.2. JMS configuration bean
<bean id="jmsConfig" class="org.apache.cxf.transport.jms.JMSConfiguration" p:connectionFactory-ref="connectionFactory" p:targetDestination="dynamicQueues/greeter.request.queue" p:pubSubDomain="false" />
Applying the configuration to an endpoint
JMSConfiguration
bean can be applied directly to both server and client endpoints using the Apache CXF features mechanism. To do so:
- Set the endpoint's
address
attribute tojms://
. - Add a
jaxws:feature
element to the endpoint's configuration. - Add a bean of type
org.apache.cxf.transport.jms.JMSConfigFeature
to the feature. - Set the
bean
element'sp:jmsConfig-ref
attribute to the ID of theJMSConfiguration
bean.
Example 34.3. Adding JMS configuration to a JAX-WS client
<jaxws:client id="CustomerService" xmlns:customer="http://customerservice.example.com/" serviceName="customer:CustomerServiceService" endpointName="customer:CustomerServiceEndpoint" address="jms://" serviceClass="com.example.customerservice.CustomerService"> <jaxws:features> <bean class="org.apache.cxf.transport.jms.JMSConfigFeature" p:jmsConfig-ref="jmsConfig"/> </jaxws:features> </jaxws:client>
Applying the configuration to the transport
JMSConfiguration
bean can be applied to JMS conduits and JMS destinations using the jms:jmsConfig-ref
element. The jms:jmsConfig-ref
element's value is the ID of the JMSConfiguration
bean.
Example 34.4. Adding JMS configuration to a JMS conduit
<jms:conduit name="{http://cxf.apache.org/jms_conf_test}HelloWorldQueueBinMsgPort.jms-conduit"> ... <jms:jmsConfig-ref>jmsConf</jms:jmsConfig-ref> </jms:conduit>
34.2. Configuring the Jetty Runtime
Overview
Maven dependency
pom.xml
file:
<dependency> <groupId>org.apache.cxf</groupId> <artifactId>cxf-rt-transports-http-jetty</artifactId> <version>${cxf-version}</version> </dependency>
Namespace
httpj
. In order to use the Jetty configuration elements you must add the lines shown in Example 34.5, “Jetty Runtime Configuration Namespace” to the beans
element of your endpoint's configuration file. In addition, you must add the configuration elements' namespace to the xsi:schemaLocation
attribute.
Example 34.5. Jetty Runtime Configuration Namespace
<beans ... xmlns:httpj="http://cxf.apache.org/transports/http-jetty/configuration" ... xsi:schemaLocation="... http://cxf.apache.org/transports/http-jetty/configuration http://cxf.apache.org/schemas/configuration/http-jetty.xsd ...">
The engine-factory
element
httpj:engine-factory
element is the root element used to configure the Jetty runtime used by an application. It has a single required attribute, bus
, whose value is the name of the Bus
that manages the Jetty instances being configured.
cxf
which is the name of the default Bus
instance.
httpj:engine-factory
element has three children that contain the information used to configure the HTTP ports instantiated by the Jetty runtime factory. The children are described in Table 34.2, “Elements for Configuring a Jetty Runtime Factory”.
Table 34.2. Elements for Configuring a Jetty Runtime Factory
Element | Description |
---|---|
httpj:engine |
Specifies the configuration for a particular Jetty runtime instance. See the section called “The
engine element”.
|
httpj:identifiedTLSServerParameters |
Specifies a reusable set of properties for securing an HTTP service provider. It has a single attribute,
id , that specifies a unique identifier by which the property set can be referred.
|
httpj:identifiedThreadingParameters |
Specifies a reusable set of properties for controlling a Jetty instance's thread pool. It has a single attribute,
id , that specifies a unique identifier by which the property set can be referred.
|
The engine
element
httpj:engine
element is used to configure specific instances of the Jetty runtime. It has a single attribute, port
, that specifies the number of the port being managed by the Jetty instance.
0
for the port
attribute. Any threading properties specified in an httpj:engine
element with its port
attribute set to 0
are used as the configuration for all Jetty listeners that are not explicitly configured.
httpj:engine
element can have two children: one for configuring security properties and one for configuring the Jetty instance's thread pool. For each type of configuration you can either directly provide the configuration information or you can provide a reference to a set of configuration properties defined in the parent httpj:engine-factory
element.
Table 34.3. Elements for Configuring a Jetty Runtime Instance
Element | Description |
---|---|
httpj:tlsServerParameters |
Specifies a set of properties for configuring the security used for the specific Jetty instance.
|
httpj:tlsServerParametersRef |
Refers to a set of security properties defined by a
identifiedTLSServerParameters element. The id attribute provides the id of the referred identifiedTLSServerParameters element.
|
httpj:threadingParameters |
Specifies the size of the thread pool used by the specific Jetty instance. See the section called “Configuring the thread pool”.
|
httpj:threadingParametersRef |
Refers to a set of properties defined by a
identifiedThreadingParameters element. The id attribute provides the id of the referred identifiedThreadingParameters element.
|
Configuring the thread pool
- Specifying the size of the thread pool using a
identifiedThreadingParameters
element in theengine-factory
element. You then refer to the element using athreadingParametersRef
element. - Specifying the size of the of the thread pool directly using a
threadingParameters
element.
threadingParameters
has two attributes to specify the size of a thread pool. The attributes are described in Table 34.4, “Attributes for Configuring a Jetty Thread Pool”.
httpj:identifiedThreadingParameters
element has a single child threadingParameters
element.
Example
Example 34.6. Configuring a Jetty Instance
<beans xmlns="http://www.springframework.org/schema/beans" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:sec="http://cxf.apache.org/configuration/security" xmlns:http="http://cxf.apache.org/transports/http/configuration" xmlns:httpj="http://cxf.apache.org/transports/http-jetty/configuration" xmlns:jaxws="http://java.sun.com/xml/ns/jaxws" xsi:schemaLocation="http://cxf.apache.org/configuration/security http://cxf.apache.org/schemas/configuration/security.xsd http://cxf.apache.org/transports/http/configuration http://cxf.apache.org/schemas/configuration/http-conf.xsd http://cxf.apache.org/transports/http-jetty/configuration http://cxf.apache.org/schemas/configuration/http-jetty.xsd http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.0.xsd"> ... <httpj:engine-factory bus="cxf"> <httpj:identifiedTLSServerParameters id="secure"> <sec:keyManagers keyPassword="password"> <sec:keyStore type="JKS" password="password" file="certs/cherry.jks"/> </sec:keyManagers> </httpj:identifiedTLSServerParameters> <httpj:engine port="9001"> <httpj:tlsServerParametersRef id="secure" /> <httpj:threadingParameters minThreads="5" maxThreads="15" /> </httpj:engine> </httpj:engine-factory> </beans>
Chapter 35. Deploying WS-Addressing
Abstract
35.1. Introduction to WS-Addressing
Overview
- A structure for communicating a reference to a Web service endpoint
- A set of Message Addressing Properties (MAP) that associate addressing information with a particular message
Supported specifications
Further information
35.2. WS-Addressing Interceptors
Overview
WS-Addressing Interceptors
Table 35.1. WS-Addressing Interceptors
Interceptor | Description |
---|---|
org.apache.cxf.ws.addressing.MAPAggregator | A logical interceptor responsible for aggregating the Message Addressing Properties (MAPs) for outgoing messages. |
org.apache.cxf.ws.addressing.soap.MAPCodec | A protocol-specific interceptor responsible for encoding and decoding the Message Addressing Properties (MAPs) as SOAP headers. |
35.3. Enabling WS-Addressing
Overview
- RMAssertion and WS-Policy Framework
- Using Policy Assertion in a WS-Addressing Feature
Adding WS-Addressing as a Feature
Example 35.1. client.xml—Adding WS-Addressing Feature to Client Configuration
<?xml version="1.0" encoding="UTF-8"?> <beans xmlns="http://www.springframework.org/schema/beans" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:jaxws="http://cxf.apache.org/jaxws" xmlns:wsa="http://cxf.apache.org/ws/addressing" xsi:schemaLocation=" http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd"> <jaxws:client ...> <jaxws:features> <wsa:addressing/> </jaxws:features> </jaxws:client> </beans>
Example 35.2. server.xml—Adding WS-Addressing Feature to Server Configuration
<?xml version="1.0" encoding="UTF-8"?> <beans xmlns="http://www.springframework.org/schema/beans" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:jaxws="http://cxf.apache.org/jaxws" xmlns:wsa="http://cxf.apache.org/ws/addressing" xsi:schemaLocation=" http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd"> <jaxws:endpoint ...> <jaxws:features> <wsa:addressing/> </jaxws:features> </jaxws:endpoint> </beans>
35.4. Configuring WS-Addressing Attributes
Overview
http://cxf.apache.org/ws/addressing
. It supports the two attributes described in Table 35.2, “WS-Addressing Attributes”.
Table 35.2. WS-Addressing Attributes
Attribute Name | Value |
---|---|
allowDuplicates | A boolean that determines if duplicate MessageIDs are tolerated. The default setting is true . |
usingAddressingAdvisory | A boolean that indicates if the presence of the UsingAddressing element in the WSDL is advisory only; that is, its absence does not prevent the encoding of WS-Addressing headers. |
Configuring WS-Addressing attributes
allowDublicates
attribute to false
on the server endpoint:
<beans ... xmlns:wsa="http://cxf.apache.org/ws/addressing" ...> <jaxws:endpoint ...> <jaxws:features> <wsa:addressing allowDuplicates="false"/> </jaxws:features> </jaxws:endpoint> </beans>
Using a WS-Policy assertion embedded in a feature
policies
element.
Example 35.3. Using the Policies to Configure WS-Addressing
<?xml version="1.0" encoding="UTF-8"?> <beans xmlns="http://www.springframework.org/schema/beans" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:wsa="http://cxf.apache.org/ws/addressing" xmlns:wsp="http://www.w3.org/2006/07/ws-policy" xmlns:policy="http://cxf.apache.org/policy-config" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd" xmlns:jaxws="http://cxf.apache.org/jaxws" xsi:schemaLocation=" http://www.w3.org/2006/07/ws-policy http://www.w3.org/2006/07/ws-policy.xsd http://cxf.apache.org/ws/addressing http://cxf.apache.org/schema/ws/addressing.xsd http://cxf.apache.org/jaxws http://cxf.apache.org/schemas/jaxws.xsd http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd"> <jaxws:endpoint name="{http://cxf.apache.org/greeter_control}GreeterPort" createdFromAPI="true"> <jaxws:features> <policy:policies> <wsp:Policy xmlns:wsam="http://www.w3.org/2007/02/addressing/metadata"> <wsam:Addressing> <wsp:Policy> <wsam:NonAnonymousResponses/> </wsp:Policy> </wsam:Addressing> </wsp:Policy> <policy:policies> </jaxws:features> </jaxws:endpoint> </beans>
Chapter 36. Enabling Reliable Messaging
Abstract
36.1. Introduction to WS-RM
Overview
How WS-RM works
Figure 36.1. Web Services Reliable Messaging
- The RM source sends a
CreateSequence
protocol message to the RM destination. This contains a reference for the endpoint that receives acknowledgements (thewsrm:AcksTo
endpoint). - The RM destination sends a
CreateSequenceResponse
protocol message back to the RM source. This message contains the sequence ID for the RM sequence session. - The RM source adds an RM
Sequence
header to each message sent by the application source. This header contains the sequence ID and a unique message ID. - The RM source transmits each message to the RM destination.
- The RM destination acknowledges the receipt of the message from the RM source by sending messages that contain the RM
SequenceAcknowledgement
header. - The RM destination delivers the message to the application destination in an exactly-once-in-order fashion.
- The RM source retransmits a message that it has not yet received an acknowledgement.The first retransmission attempt is made after a base retransmission interval. Successive retransmission attempts are made, by default, at exponential back-off intervals or, alternatively, at fixed intervals. For more details, see Section 36.4, “Configuring WS-RM”.
WS-RM delivery assurances
Supported specifications
Further information
36.2. WS-RM Interceptors
Overview
Apache CXF WS-RM Interceptors
Table 36.1. Apache CXF WS-ReliableMessaging Interceptors
Interceptor | Description |
---|---|
org.apache.cxf.ws.rm.RMOutInterceptor |
Deals with the logical aspects of providing reliability guarantees for outgoing messages.
Responsible for sending the
CreateSequence requests and waiting for their CreateSequenceResponse responses.
Also responsible for aggregating the sequence properties—ID and message number—for an application message.
|
org.apache.cxf.ws.rm.RMInInterceptor | Responsible for intercepting and processing RM protocol messages and SequenceAcknowledgement messages that are piggybacked on application messages. |
org.apache.cxf.ws.rm.soap.RMSoapInterceptor | Responsible for encoding and decoding the reliability properties as SOAP headers. |
org.apache.cxf.ws.rm.RetransmissionInterceptor | Responsible for creating copies of application messages for future resending. |
Enabling WS-RM
RMOutInterceptor
sends a CreateSequence
request and waits to process the original application message until it receives the CreateSequenceResponse
response. In addition, the WS-RM interceptors add the sequence headers to the application messages and, on the destination side, extract them from the messages. It is not necessary to make any changes to your application code to make the exchange of messages reliable.
Configuring WS-RM Attributes
1
).
36.3. Enabling WS-RM
Overview
- Explicitly, by adding them to the dispatch chains using Spring beans
- Implicitly, using WS-Policy assertions, which cause the Apache CXF runtime to transparently add the interceptors on your behalf.
Spring beans—explicitly adding interceptors
InstallDir/samples/ws_rm
directory. The configuration file, ws-rm.cxf
, shows the WS-RM and WS-Addressing interceptors being added one-by-one as Spring beans (see Example 36.1, “Enabling WS-RM Using Spring Beans”).
Example 36.1. Enabling WS-RM Using Spring Beans
<?xml version="1.0" encoding="UTF-8"?> 1<beans xmlns="http://www.springframework.org/schema/beans" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.springframework.org/schema/ beans http://www.springframework.org/schema/beans/spring-beans.xsd"> 2 <bean id="mapAggregator" class="org.apache.cxf.ws.addressing.MAPAggregator"/> <bean id="mapCodec" class="org.apache.cxf.ws.addressing.soap.MAPCodec"/> 3 <bean id="rmLogicalOut" class="org.apache.cxf.ws.rm.RMOutInterceptor"> <property name="bus" ref="cxf"/> </bean> <bean id="rmLogicalIn" class="org.apache.cxf.ws.rm.RMInInterceptor"> <property name="bus" ref="cxf"/> </bean> <bean id="rmCodec" class="org.apache.cxf.ws.rm.soap.RMSoapInterceptor"/> <bean id="cxf" class="org.apache.cxf.bus.CXFBusImpl"> 4 <property name="inInterceptors"> <list> <ref bean="mapAggregator"/> <ref bean="mapCodec"/> <ref bean="rmLogicalIn"/> <ref bean="rmCodec"/> </list> </property> 5 <property name="inFaultInterceptors"> <list> <ref bean="mapAggregator"/> <ref bean="mapCodec"/> <ref bean="rmLogicalIn"/> <ref bean="rmCodec"/> </list> </property> 6 <property name="outInterceptors"> <list> <ref bean="mapAggregator"/> <ref bean="mapCodec"/> <ref bean="rmLogicalOut"/> <ref bean="rmCodec"/> </list> </property> 7 <property name="outFaultInterceptors"> <list> <ref bean="mapAggregator"> <ref bean="mapCodec"/> <ref bean="rmLogicalOut"/> <ref bean="rmCodec"/> </list> </property> </bean> </beans>
- 1
- A Apache CXF configuration file is a Spring XML file. You must include an opening Spring
beans
element that declares the namespaces and schema files for the child elements that are encapsulated by thebeans
element. - 2
- Configures each of the WS-Addressing interceptors—
MAPAggregator
andMAPCodec
. For more information on WS-Addressing, see Chapter 35, Deploying WS-Addressing. - 3
- Configures each of the WS-RM interceptors—
RMOutInterceptor
,RMInInterceptor
, andRMSoapInterceptor
. - 4
- Adds the WS-Addressing and WS-RM interceptors to the interceptor chain for inbound messages.
- 5
- Adds the WS-Addressing and WS-RM interceptors to the interceptor chain for inbound faults.
- 6
- Adds the WS-Addressing and WS-RM interceptors to the interceptor chain for outbound messages.
- 7
- Adds the WS-Addressing and WS-RM interceptors to the interceptor chain for outbound faults.
WS-Policy framework—implicitly adding interceptors
- Add the policy feature to your client and server endpoint. Example 36.2, “Configuring WS-RM using WS-Policy” shows a reference bean nested within a
jaxws:feature
element. The reference bean specifies theAddressingPolicy
, which is defined as a separate element within the same configuration file.Example 36.2. Configuring WS-RM using WS-Policy
<jaxws:client> <jaxws:features> <ref bean="AddressingPolicy"/> </jaxws:features> </jaxws:client> <wsp:Policy wsu:Id="AddressingPolicy" xmlns:wsam="http://www.w3.org/2007/02/addressing/metadata"> <wsam:Addressing> <wsp:Policy> <wsam:NonAnonymousResponses/> </wsp:Policy> </wsam:Addressing> </wsp:Policy>
- Add a reliable messaging policy to the
wsdl:service
element—or any other WSDL element that can be used as an attachment point for policy or policy reference elements—to your WSDL file, as shown in Example 36.3, “Adding an RM Policy to Your WSDL File”.Example 36.3. Adding an RM Policy to Your WSDL File
<wsp:Policy wsu:Id="RM" xmlns:wsp="http://www.w3.org/2006/07/ws-policy" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"> <wsam:Addressing xmlns:wsam="http://www.w3.org/2007/02/addressing/metadata"> <wsp:Policy/> </wsam:Addressing> <wsrmp:RMAssertion xmlns:wsrmp="http://schemas.xmlsoap.org/ws/2005/02/rm/policy"> <wsrmp:BaseRetransmissionInterval Milliseconds="10000"/> </wsrmp:RMAssertion> </wsp:Policy> ... <wsdl:service name="ReliableGreeterService"> <wsdl:port binding="tns:GreeterSOAPBinding" name="GreeterPort"> <soap:address location="http://localhost:9020/SoapContext/GreeterPort"/> <wsp:PolicyReference URI="#RM" xmlns:wsp="http://www.w3.org/2006/07/ws-policy"/> </wsdl:port> </wsdl:service>
36.4. Configuring WS-RM
- Setting Apache CXF-specific attributes that are defined in the Apache CXF WS-RM manager namespace,
http://cxf.apache.org/ws/rm/manager
. - Setting standard WS-RM policy attributes that are defined in the http://schemas.xmlsoap.org/ws/2005/02/rm/policy namespace.
36.4.1. Configuring Apache CXF-Specific WS-RM Attributes
Overview
rmManager
Spring bean. Add the following to your configuration file:
- The
http://cxf.apache.org/ws/rm/manager
namespace to your list of namespaces. - An
rmManager
Spring bean for the specific attribute that your want to configure.
Example 36.4. Configuring Apache CXF-Specific WS-RM Attributes
<beans xmlns="http://www.springframework.org/schema/beans" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:wsrm-mgr="http://cxf.apache.org/ws/rm/manager" xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd http://cxf.apache.org/ws/rm/manager http://cxf.apache.org/schemas/configuration/wsrm-manager.xsd"> ... <wsrm-mgr:rmManager> <!-- ...Your configuration goes here --> </wsrm-mgr:rmManager>
Children of the rmManager Spring bean
rmManager
Spring bean, defined in the http://cxf.apache.org/ws/rm/manager
namespace.
Table 36.2. Children of the rmManager Spring Bean
Element | Description |
---|---|
RMAssertion | An element of type RMAssertion |
deliveryAssurance | An element of type DeliveryAssuranceType that describes the delivery assurance that should apply |
sourcePolicy | An element of type SourcePolicyType that allows you to configure details of the RM source |
destinationPolicy | An element of type DestinationPolicyType that allows you to configure details of the RM destination |
Example
36.4.2. Configuring Standard WS-RM Policy Attributes
Overview
WS-Policy RMAssertion Children
http://schemas.xmlsoap.org/ws/2005/02/rm/policy
namespace:
Table 36.3. Children of the WS-Policy RMAssertion Element
Name | Description |
---|---|
InactivityTimeout | Specifies the amount of time that must pass without receiving a message before an endpoint can consider an RM sequence to have been terminated due to inactivity. |
BaseRetransmissionInterval | Sets the interval within which an acknowledgement must be received by the RM Source for a given message. If an acknowledgement is not received within the time set by the BaseRetransmissionInterval , the RM Source will retransmit the message. |
ExponentialBackoff |
Indicates the retransmission interval will be adjusted using the commonly known exponential backoff algorithm (Tanenbaum).
For more information, see Computer Networks, Andrew S. Tanenbaum, Prentice Hall PTR, 2003.
|
AcknowledgementInterval | In WS-RM, acknowledgements are sent on return messages or sent stand-alone. If a return message is not available to send an acknowledgement, an RM Destination can wait for up to the acknowledgement interval before sending a stand-alone acknowledgement. If there are no unacknowledged messages, the RM Destination can choose not to send an acknowledgement. |
More detailed reference information
RMAssertion in rmManager Spring bean
RMAssertion
within a Apache CXF rmManager
Spring bean. This is the best approach if you want to keep all of your WS-RM configuration in the same configuration file; that is, if you want to configure Apache CXF-specific attributes and standard WS-RM policy attributes in the same file.
- A standard WS-RM policy attribute,
BaseRetransmissionInterval
, configured using anRMAssertion
within anrmManager
Spring bean. - An Apache CXF-specific RM attribute,
intraMessageThreshold
, configured in the same configuration file.
Example 36.5. Configuring WS-RM Attributes Using an RMAssertion in an rmManager Spring Bean
<beans xmlns:wsrm-policy="http://schemas.xmlsoap.org/ws/2005/02/rm/policy" xmlns:wsrm-mgr="http://cxf.apache.org/ws/rm/manager" ...> <wsrm-mgr:rmManager id="org.apache.cxf.ws.rm.RMManager"> <wsrm-policy:RMAssertion> <wsrm-policy:BaseRetransmissionInterval Milliseconds="4000"/> </wsrm-policy:RMAssertion> <wsrm-mgr:destinationPolicy> <wsrm-mgr:acksPolicy intraMessageThreshold="0" /> </wsrm-mgr:destinationPolicy> </wsrm-mgr:rmManager> </beans>
Policy within a feature
Example 36.6. Configuring WS-RM Attributes as a Policy within a Feature
<xml version="1.0" encoding="UTF-8"?> <beans xmlns="http://www.springframework.org/schema/beans" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:wsa="http://cxf.apache.org/ws/addressing" xmlns:wsp="http://www.w3.org/2006/07/ws-policy" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd" xmlns:jaxws="http://cxf.apache.org/jaxws" xsi:schemaLocation=" http://www.w3.org/2006/07/ws-policy http://www.w3.org/2006/07/ws-policy.xsd http://cxf.apache.org/ws/addressing http://cxf.apache.org/schema/ws/addressing.xsd http://cxf.apache.org/jaxws http://cxf.apache.org/schemas/jaxws.xsd http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd"> <jaxws:endpoint name="{http://cxf.apache.org/greeter_control}GreeterPort" createdFromAPI="true"> <jaxws:features> <wsp:Policy> <wsrm:RMAssertion xmlns:wsrm="http://schemas.xmlsoap.org/ws/2005/02/rm/policy"> <wsrm:AcknowledgementInterval Milliseconds="200" /> </wsrm:RMAssertion> <wsam:Addressing xmlns:wsam="http://www.w3.org/2007/02/addressing/metadata"> <wsp:Policy> <wsam:NonAnonymousResponses/> </wsp:Policy> </wsam:Addressing> </wsp:Policy> </jaxws:features> </jaxws:endpoint> </beans>
WSDL file
External attachment
Example 36.7. Configuring WS-RM in an External Attachment
<attachments xmlns:wsp="http://www.w3.org/2006/07/ws-policy" xmlns:wsa="http://www.w3.org/2005/08/addressing"> <wsp:PolicyAttachment> <wsp:AppliesTo> <wsa:EndpointReference> <wsa:Address>http://localhost:9020/SoapContext/GreeterPort</wsa:Address> </wsa:EndpointReference> </wsp:AppliesTo> <wsp:Policy> <wsam:Addressing xmlns:wsam="http://www.w3.org/2007/02/addressing/metadata"> <wsp:Policy/> </wsam:Addressing> <wsrmp:RMAssertion xmlns:wsrmp="http://schemas.xmlsoap.org/ws/2005/02/rm/policy"> <wsrmp:BaseRetransmissionInterval Milliseconds="30000"/> </wsrmp:RMAssertion> </wsp:Policy> </wsp:PolicyAttachment> </attachments>/
36.4.3. WS-RM Configuration Use Cases
Overview
RMAssertion
within an rmManager
Spring bean is shown. For details of how to set such attributes as a policy within a feature; in a WSDL file, or in an external attachment, see Section 36.4.2, “Configuring Standard WS-RM Policy Attributes”.
Base retransmission interval
BaseRetransmissionInterval
element specifies the interval at which an RM source retransmits a message that has not yet been acknowledged. It is defined in the http://schemas.xmlsoap.org/ws/2005/02/rm/wsrm-policy.xsd schema file. The default value is 3000 milliseconds.
Example 36.8. Setting the WS-RM Base Retransmission Interval
<beans xmlns:wsrm-policy="http://schemas.xmlsoap.org/ws/2005/02/rm/policy ...> <wsrm-mgr:rmManager id="org.apache.cxf.ws.rm.RMManager"> <wsrm-policy:RMAssertion> <wsrm-policy:BaseRetransmissionInterval Milliseconds="4000"/> </wsrm-policy:RMAssertion> </wsrm-mgr:rmManager> </beans>
Exponential backoff for retransmission
ExponentialBackoff
element determines if successive retransmission attempts for an unacknowledged message are performed at exponential intervals.
ExponentialBackoff
element enables this feature. An exponential backoff ratio of 2
is used by default.
Example 36.9. Setting the WS-RM Exponential Backoff Property
<beans xmlns:wsrm-policy="http://schemas.xmlsoap.org/ws/2005/02/rm/policy ...> <wsrm-mgr:rmManager id="org.apache.cxf.ws.rm.RMManager"> <wsrm-policy:RMAssertion> <wsrm-policy:ExponentialBackoff="4"/> </wsrm-policy:RMAssertion> </wsrm-mgr:rmManager> </beans>
Acknowledgement interval
AcknowledgementInterval
element specifies the interval at which the WS-RM destination sends asynchronous acknowledgements. These are in addition to the synchronous acknowledgements that it sends on receipt of an incoming message. The default asynchronous acknowledgement interval is 0
milliseconds. This means that if the AcknowledgementInterval
is not configured to a specific value, acknowledgements are sent immediately (that is, at the first available opportunity).
- The RM destination is using a non-anonymous
wsrm:acksTo
endpoint. - The opportunity to piggyback an acknowledgement on a response message does not occur before the expiry of the acknowledgement interval.
Example 36.10. Setting the WS-RM Acknowledgement Interval
<beans xmlns:wsrm-policy="http://schemas.xmlsoap.org/ws/2005/02/rm/policy ...> <wsrm-mgr:rmManager id="org.apache.cxf.ws.rm.RMManager"> <wsrm-policy:RMAssertion> <wsrm-policy:AcknowledgementInterval Milliseconds="2000"/> </wsrm-policy:RMAssertion> </wsrm-mgr:rmManager> </beans>
Maximum unacknowledged messages threshold
maxUnacknowledged
attribute sets the maximum number of unacknowledged messages that can accrue per sequence before the sequence is terminated.
Example 36.11. Setting the WS-RM Maximum Unacknowledged Message Threshold
<beans xmlns:wsrm-mgr="http://cxf.apache.org/ws/rm/manager ...> <wsrm-mgr:reliableMessaging> <wsrm-mgr:sourcePolicy> <wsrm-mgr:sequenceTerminationPolicy maxUnacknowledged="20" /> </wsrm-mgr:sourcePolicy> </wsrm-mgr:reliableMessaging> </beans>
Maximum length of an RM sequence
maxLength
attribute sets the maximum length of a WS-RM sequence. The default value is 0
, which means that the length of a WS-RM sequence is unbound.
Example 36.12. Setting the Maximum Length of a WS-RM Message Sequence
<beans xmlns:wsrm-mgr="http://cxf.apache.org/ws/rm/manager ...> <wsrm-mgr:reliableMessaging> <wsrm-mgr:sourcePolicy> <wsrm-mgr:sequenceTerminationPolicy maxLength="100" /> </wsrm-mgr:sourcePolicy> </wsrm-mgr:reliableMessaging> </beans>
Message delivery assurance policies
AtMostOnce
— The RM destination delivers the messages to the application destination only once. If a message is delivered more than once an error is raised. It is possible that some messages in a sequence may not be delivered.AtLeastOnce
— The RM destination delivers the messages to the application destination at least once. Every message sent will be delivered or an error will be raised. Some messages might be delivered more than once.InOrder
— The RM destination delivers the messages to the application destination in the order that they are sent. This delivery assurance can be combined with theAtMostOnce
orAtLeastOnce
assurances.
Example 36.13. Setting the WS-RM Message Delivery Assurance Policy
<beans xmlns:wsrm-mgr="http://cxf.apache.org/ws/rm/manager ...> <wsrm-mgr:reliableMessaging> <wsrm-mgr:deliveryAssurance> <wsrm-mgr:AtLeastOnce /> </wsrm-mgr:deliveryAssurance> </wsrm-mgr:reliableMessaging> </beans>
36.5. Configuring WS-RM Persistence
Overview
How it works
- At the RM source endpoint, an outgoing message is persisted before transmission. It is evicted from the persistent store after the acknowledgement is received.
- After a recovery from crash, it recovers the persisted messages and retransmits until all the messages have been acknowledged. At that point, the RM sequence is closed.
- At the RM destination endpoint, an incoming message is persisted, and upon a successful store, the acknowledgement is sent. When a message is successfully dispatched, it is evicted from the persistent store.
- After a recovery from a crash, it recovers the persisted messages and dispatches them. It also brings the RM sequence to a state where new messages are accepted, acknowledged, and delivered.
Enabling WS-persistence
Example 36.14. Configuration for the Default WS-RM Persistence Store
<bean id="RMTxStore" class="org.apache.cxf.ws.rm.persistence.jdbc.RMTxStore"/> <wsrm-mgr:rmManager id="org.apache.cxf.ws.rm.RMManager"> <property name="store" ref="RMTxStore"/> </wsrm-mgr:rmManager>
Configuring WS-persistence
Table 36.4. JDBC Store Properties
Example 36.15. Configuring the JDBC Store for WS-RM Persistence
<bean id="RMTxStore" class="org.apache.cxf.ws.rm.persistence.jdbc.RMTxStore"> <property name="driverClassName" value="com.acme.jdbc.Driver"/> <property name="url" value="jdbc:acme:rmdb;create=true"/> </bean>
Appendix F. Consumer Endpoint Properties
Table F.1. Consumer Endpoint Attributes
Name | Type | Description | Required |
---|---|---|---|
wsdl | String | Specifies the location of the WSDL defining the endpoint. | yes |
service | QName | Specifies the service name of the proxied endpoint. This corresponds to WSDL service element's name attribute. | no[a] |
endpoint | String | Specifies the endpoint name of the proxied endpoint. This corresponds to WSDL port element's name attribute. | no[b] |
interfaceName | QName | Specifies the interface name of the proxied endpoint. This corresponds to WSDL portType element's name attribute. | no |
targetService | QName | Specifies the service name of the target endpoint. | no (defaults to the value of the service attribute) |
targetEndpoint | String | Specifies the endpoint name of the target endpoint. | no (defaults to the value of the endpoint attribute) |
targetInterfaceName | QName | Specifies the interface name of the target endpoint. | no |
busCfg | String | Specifies the location of a spring configuration file used for Apache CXF bus initialization. | no |
mtomEnabled | boolean | Specifies if MTOM / attachment support is enabled. | no (defaults to false ) |
useJbiWrapper | boolean | Specifies if the JBI wrapper is sent in the body of the message. | no (defaults to true ) |
timeout | int | Specifies the number of seconds to wait for a response. | no (defaults to 10 |
[a]
If the WSDL defining the service has more than one service element, this attribute is required.
[b]
If the service being used defines more than one endpoint, this attribute is required.
|
Appendix G. Provider Endpoint Properties
Table G.1. Provider Endpoint Attributes
Attribute | Type | Description | Required |
---|---|---|---|
wsdl | String | Specifies the location of the WSDL defining the endpoint. | yes |
service | QName | Specifies the service name of the exposed endpoint. | no[a] |
endpoint | String | Specifies the endpoint name of the exposed endpoint. | no[b] |
locationURI | URI | Specifies the URL of the target service. | no[c][d] |
interfaceName | QName | Specifies the interface name of the exposed jbi endpoint. | no |
busCfg | String | Specifies the location of the spring configuration file used for Apache CXF bus initialization. | no |
mtomEnabled | boolean | Specifies if MTOM / attachment support is enabled. | no (defaults to false ) |
useJbiWrapper | boolean | Specifies if the JBI wrapper is sent in the body of the message. | no (defaults to true ) |
[a]
If the WSDL defining the service has more than one service element, this attribute is required.
[b]
If the service being used defines more than one endpoint, this attribute is required.
[c]
If specified, the value of this attribute overrides the HTTP address specified in the WSDL contract.
[d]
This attribute is ignored if the endpoint uses a JMS address in the WSDL.
|
Appendix H. Using the Maven OSGi Tooling
Abstract
H.1. Setting up a Red Hat JBoss Fuse OSGi project
Overview
Directory structure
src
folder. As in all Maven projects, you place all Java source code in the src/java
folder, and you place any non-Java resources in the src/resources
folder.
beans.xml
file located in the src/resources/META-INF/spring
folder.
Adding a bundle plug-in
Example H.1. Adding an OSGi bundle plug-in to a POM
... <dependencies> <dependency> 1 <groupId>org.apache.felix</groupId> <artifactId>org.osgi.core</artifactId> <version>1.0.0</version> </dependency> ... </dependencies> ... <build> <plugins> <plugin> 2 <groupId>org.apache.felix</groupId> <artifactId>maven-bundle-plugin</artifactId> <configuration> <instructions> <Bundle-SymbolicName>${pom.artifactId}</Bundle-SymbolicName> 3 <Import-Package>*,org.apache.camel.osgi</Import-Package> 4 <Private-Package>org.apache.servicemix.examples.camel</Private-Package> 5 </instructions> </configuration> </plugin> </plugins> </build> ...
- 1
- Adds the dependency on Apache Felix
- 2
- Adds the bundle plug-in to your project
- 3
- Configures the plug-in to use the project's artifact ID as the bundle's symbolic name
- 4
- Configures the plug-in to include all Java packages imported by the bundled classes; also imports the org.apache.camel.osgi package
- 5
- Configures the plug-in to bundle the listed class, but not to include them in the list of exported packages
Activating a bundle plug-in
packaging
element to bundle
.
Useful Maven archetypes
Spring OSGi archetype
org.springframework.osgi/spring-bundle-osgi-archetype/1.1.2
mvn archetype:create -DarchetypeGroupId=org.springframework.osgi -DarchetypeArtifactId=spring-osgi-bundle-archetype -DarchetypeVersion=1.12 -DgroupId=groupId -DartifactId=artifactId -Dversion=version
Apache CXF code-first archetype
org.apache.servicemix.tooling/servicemix-osgi-cxf-code-first-archetype/2008.01.0.3-fuse
mvn archetype:create -DarchetypeGroupId=org.apache.servicemix.tooling -DarchetypeArtifactId=spring-osgi-bundle-archetype -DarchetypeVersion=2008.01.0.3-fuse -DgroupId=groupId -DartifactId=artifactId -Dversion=version
Apache CXF wsdl-first archetype
org.apache.servicemix.tooling/servicemix-osgi-cxf-wsdl-first-archetype/2008.01.0.3-fuse
mvn archetype:create -DarchetypeGroupId=org.apache.servicemix.tooling -DarchetypeArtifactId=servicemix-osgi-cxf-wsdl-first-archetype -DarchetypeVersion=2008.01.0.3-fuse -DgroupId=groupId -DartifactId=artifactId -Dversion=version
Apache Camel archetype
org.apache.servicemix.tooling/servicemix-osgi-camel-archetype/2008.01.0.3-fuse
mvn archetype:create -DarchetypeGroupId=org.apache.servicemix.tooling -DarchetypeArtifactId=servicemix-osgi-camel-archetype -DarchetypeVersion=2008.01.0.3-fuse -DgroupId=groupId -DartifactId=artifactId -Dversion=version
H.2. Configuring the Bundle Plug-In
Overview
instructions
element.
Configuration properties
Setting a bundle's symbolic name
+ "." +
artifactId, with the following exceptions:
- If groupId has only one section (no dots), the first package name with classes is returned.For example, if the group Id is
commons-logging:commons-logging
, the bundle's symbolic name isorg.apache.commons.logging
. - If artifactId is equal to the last section of groupId, then groupId is used.For example, if the POM specifies the group ID and artifact ID as
org.apache.maven:maven
, the bundle's symbolic name isorg.apache.maven
. - If artifactId starts with the last section of groupId, that portion is removed.For example, if the POM specifies the group ID and artifact ID as
org.apache.maven:maven-core
, the bundle's symbolic name isorg.apache.maven.core
.
Bundle-SymbolicName
child in the plug-in's instructions
element, as shown in Example H.2.
Example H.2. Setting a bundle's symbolic name
<plugin>
<groupId>org.apache.felix</groupId>
<artifactId>maven-bundle-plugin</artifactId>
<configuration>
<instructions>
<Bundle-SymbolicName>${project.artifactId}</Bundle-SymbolicName>
...
</instructions>
</configuration>
</plugin>
Setting a bundle's name
${project.name}
.
Bundle-Name
child to the plug-in's instructions
element, as shown in Example H.3.
Example H.3. Setting a bundle's name
<plugin>
<groupId>org.apache.felix</groupId>
<artifactId>maven-bundle-plugin</artifactId>
<configuration>
<instructions>
<Bundle-Name>JoeFred</Bundle-Name>
...
</instructions>
</configuration>
</plugin>
Setting a bundle's version
${project.version}
. Any dashes (-
) are replaced with dots (.
) and the number is padded up to four digits. For example, 4.2-SNAPSHOT
becomes 4.2.0.SNAPSHOT
.
Bundle-Version
child to the plug-in's instructions
element, as shown in Example H.4.
Example H.4. Setting a bundle's version
<plugin>
<groupId>org.apache.felix</groupId>
<artifactId>maven-bundle-plugin</artifactId>
<configuration>
<instructions>
<Bundle-Version>1.0.3.1</Bundle-Version>
...
</instructions>
</configuration>
</plugin>
Specifying exported packages
Export-Package
list is populated by all of the packages in your local Java source code (under src/main/java
), except for the deault package, .
, and any packages containing .impl
or .internal
.
Private-Package
element in your plug-in configuration and you do not specify a list of packages to export, the default behavior includes only the packages listed in the Private-Package
element in the bundle. No packages are exported.
Export-Package
child to the plug-in's instructions
element.
Export-Package
element specifies a list of packages that are to be included in the bundle and that are to be exported. The package names can be specified using the *
wildcard symbol. For example, the entry com.fuse.demo.*
includes all packages on the project's classpath that start with com.fuse.demo.
!
. For example, the entry !com.fuse.demo.private
excludes the package com.fuse.demo.private.
!com.fuse.demo.private,com.fuse.demo.*
Specifying private packages
Private-Package
instruction to the bundle plug-in configuration. By default, if you do not specify a Private-Package
instruction, all packages in your local Java source are included in the bundle.
Private-Package
element and the Export-Package
element, the Export-Package
element takes precedence. The package is added to the bundle and exported.
Private-Package
element works similarly to the Export-Package
element in that you specify a list of packages to be included in the bundle. The bundle plug-in uses the list to find all classes on the project's classpath that are to be included in the bundle. These packages are packaged in the bundle, but not exported (unless they are also selected by the Export-Package
instruction).
Example H.5. Including a private package in a bundle
<plugin>
<groupId>org.apache.felix</groupId>
<artifactId>maven-bundle-plugin</artifactId>
<configuration>
<instructions>
<Private-Package>org.apache.cxf.wsdlFirst.impl</Private-Package>
...
</instructions>
</configuration>
</plugin>
Specifying imported packages
Import-Package
property with a list of all the packages referred to by the contents of the bundle.
Import-Package
child to the plug-in's instructions
element. The syntax for the package list is the same as for the Export-Package
element and the Private-Package
element.
Import-Package
element, the plug-in does not automatically scan the bundle's contents to determine if there are any required imports. To ensure that the contents of the bundle are scanned, you must place an *
as the last entry in the package list.
Example H.6. Specifying the packages imported by a bundle
<plugin> <groupId>org.apache.felix</groupId> <artifactId>maven-bundle-plugin</artifactId> <configuration> <instructions> <Import-Package>javax.jws, javax.wsdl, org.apache.cxf.bus, org.apache.cxf.bus.spring, org.apache.cxf.bus.resource, org.apache.cxf.configuration.spring, org.apache.cxf.resource, org.springframework.beans.factory.config, * </Import-Package> ... </instructions> </configuration> </plugin>
More information
Index
A
- AcknowledgementInterval, Acknowledgement interval
- all element, Complex type varieties
- AMQPool, Using Apache ActiveMQ Connection Factories
- JCA, JCA pool
- simple, Simple pool
- XA, XA pool
- amqpool:jca-pool, JCA pool
- amqpool:pool, Simple pool
- id, Simple pool
- maxConnections, Simple pool
- maximumActive, Simple pool
- url, Simple pool
- amqpool:xa-pool, XA pool
- Ant task
- install-component, Installing a component
- install-shared-library, Installing a shared library
- installing components, Installing a component, Installing a component
- installing shared libraries, Installing a shared library, Installing a shared library
- jbi-install-component, Installing a component
- jbi-install-shared-library, Installing a shared library
- jbi-shut-down-component, Shutting down a component
- jbi-start-component, Starting a component
- jbi-stop-component, Stopping a component
- jbi-uninstall-component, Removing a component
- jbi-uninstall-shared-library, Removing a shared library
- removing components, Removing a component, Removing a shared library, Removing a component
- removing shared libraries, Removing a shared library
- shutdown-component, Shutting down a component
- shutting down components, Shutting down a component, Shutting down a component
- start-component, Starting a component
- starting components, Starting a component, Starting a component
- stop-component, Stopping a component
- stopping components, Stopping a component, Stopping a component
- uninstall-component, Removing a component
- uninstall-shared-library, Removing a shared library
- uninstalling components, Removing a component, Removing a shared library, Removing a component
- application source, How WS-RM works
- AtLeastOnce, Message delivery assurance policies
- AtMostOnce, Message delivery assurance policies
- attribute element, Defining attributes
- name attribute, Defining attributes
- type attribute, Defining attributes
- use attribute, Defining attributes
B
- BaseRetransmissionInterval, Base retransmission interval
- binary files, Provided file marshalers
- BinaryFileMarshaler, Provided file marshalers
- attachment, Provided file marshalers
- contentType, Provided file marshalers
- binding component, Component types
- binding element, WSDL elements
- Bundle-Name, Setting a bundle's name
- Bundle-SymbolicName, Setting a bundle's symbolic name
- Bundle-Version, Setting a bundle's version
- bundles
- exporting packages, Specifying exported packages
- importing packages, Specifying imported packages
- name, Setting a bundle's name
- private packages, Specifying private packages
- symbolic name, Setting a bundle's symbolic name
- version, Setting a bundle's version
C
- choice element, Complex type varieties
- clustering JBI endpoints, Overview
- complex types
- all type, Complex type varieties
- choice type, Complex type varieties
- elements, Defining the parts of a structure
- occurrence constraints, Defining the parts of a structure
- sequence type, Complex type varieties
- complexType element, Defining data structures
- component life-cycle, Managing JBI components
- componentName, Specifying the target components
- concrete part, The concrete part
- configuration
- HTTP thread pool, Configuring the thread pool
- Jetty engine, The engine-factory element
- Jetty instance, The engine element
- connection factory
- AMQPool (see AMQPool)
- Apache ActiveMQ, Using Apache ActiveMQ Connection Factories
- pooled (see AMQPool)
- ConnectionFactory, Procedure, Procedure, Procedure
- consumer, Component roles, Types of consumer endpoints
- busCfg, Specifying the configuration to load
- cacheLevel, Performace tuning using the listener container
- clientId, Performace tuning using the listener container
- concurrentConsumers, Performace tuning using the listener container
- connectionFactory, Procedure
- destination, Configuring a destination
- destinationChooser, Determining the reply destination, Configuring an endpoint to use a destination chooser
- destinationName, Configuring a destination
- destinationResolver, Configuring an endpoint to use a destination resolver
- durableSubscriberName, Using durable subscriptions
- endpoint, Procedure, Specifying the endpoint details, Specifying the endpoint details
- generic, Types of consumer endpoints
- JCA, Types of consumer endpoints
- jms102, Procedure
- listenerType, Specifying an endpoint's listener container
- marshaler, Configuring the consumer
- maxMessagesPerTask, Performace tuning using the listener container
- messageSelector, Using message selectors
- mtomEnabled, Configuring an endpoint to support MTOM
- pubSubDomaim, Procedure
- receiveTimeout, Performace tuning using the listener container
- recoveryInterval, Performace tuning using the listener container
- replyDeliveryMode, Setting the reply message's persistence
- replyDestination, Determining the reply destination
- replyDestinationName, Determining the reply destination
- replyExplicitQosEnabled, Enforcing the configured values
- replyPriority, Setting the reply message's priority
- replyProperties, Setting custom JMS header properties
- replyTimeToLive, Setting a reply message's lifespan
- serverSessionFactory, Configuring the server session listener container's session factory
- service, Procedure, Specifying the endpoint details, Specifying the endpoint details
- soap, Types of consumer endpoints
- stateless, Activating statefullness
- storeFactory, Configuring the datastore
- subscriptionDurable, Using durable subscriptions
- targetEndpoint, Specifying the target endpoint, Specifying the target endpoint
- targetInterface, Specifying the target endpoint, Specifying the target endpoint
- targetService, Specifying the target endpoint, Specifying the target endpoint
- transacted, Using transactions
- useJbiWrapper, Turning of JBI wrapper processing
- wsdl, Specifying the WSDL
- consumer endpoint, Overview
- CreateSequence, How WS-RM works
- CreateSequenceResponse, How WS-RM works
D
- DefaultConsumerMarshaler, Overview
- DefaultProviderMarshaler, Overview
- definitions element, WSDL elements
- delivery mode, Setting the reply message's persistence, Setting a message's persistence
- destination chooser, Determining the reply destination
- implementing, Implementing a destination chooser
- destination resolver
- configuration, Configuring an endpoint to use a destination resolver
- implementing, Implementing a destination resolver
- DestinationChooser, Configuring a destination, Configuring the response destination, Implementing a destination chooser
- destinationChooser, Configuring an endpoint to use a destination chooser
- DestinationResolver, Implementing a destination resolver
- destinationResolver, Configuring an endpoint to use a destination resolver
- driverClassName, Configuring WS-persistence
- durable subscriptions, Using durable subscriptions
E
- element element, Defining the parts of a structure
- maxOccurs attribute, Defining the parts of a structure
- minOccurrs attribute, Defining the parts of a structure
- name attribute, Defining the parts of a structure
- type attribute, Defining the parts of a structure
- ExponentialBackoff, Exponential backoff for retransmission
- Export-Package, Specifying exported packages
F
- file name, Specifying the file destination
- FileFilter, Overview
- accept(), Implementing a file filter
- implementing, Implementing a file filter
- FileMarshaler, Implementing a file marshaler
- getOutputName(), Implementing a file marshaler
- readMessage(), Implementing a file marshaler
- writeMessage(), Implementing a file marshaler
- filter, Configuring an endpoint to use a file filter
- flat files, Provided file marshalers
G
- getOutoutName(), Implementing a file marshaler
H
- HTTP
- endpoint address, Adding a Basic HTTP Endpoint
- http-conf:client
- Accept, Configuring the endpoint
- AcceptEncoding, Configuring the endpoint
- AcceptLanguage, Configuring the endpoint
- AllowChunking, Configuring the endpoint
- AutoRedirect, Configuring the endpoint
- BrowserType, Configuring the endpoint
- CacheControl, Configuring the endpoint, Consumer Cache Control Directives
- Connection, Configuring the endpoint
- ConnectionTimeout, Configuring the endpoint
- ContentType, Configuring the endpoint
- Cookie, Configuring the endpoint
- DecoupledEndpoint, Configuring the endpoint, Configuring the consumer
- Host, Configuring the endpoint
- MaxRetransmits, Configuring the endpoint
- ProxyServer, Configuring the endpoint
- ProxyServerPort, Configuring the endpoint
- ProxyServerType, Configuring the endpoint
- ReceiveTimeout, Configuring the endpoint
- Referer, Configuring the endpoint
- http-conf:server
- CacheControl, Configuring the endpoint
- ContentEncoding, Configuring the endpoint
- ContentLocation, Configuring the endpoint
- ContentType, Configuring the endpoint
- HonorKeepAlive, Configuring the endpoint
- ReceiveTimeout, Configuring the endpoint
- RedirectURL, Configuring the endpoint
- ServerType, Configuring the endpoint
- SuppressClientReceiveErrors, Configuring the endpoint
- SuppressClientSendErrors, Configuring the endpoint
- http:address, Other messages types
- httpj:engine, The engine element
- httpj:engine-factory, The engine-factory element
- httpj:identifiedThreadingParameters, The engine-factory element, Configuring the thread pool
- httpj:identifiedTLSServerParameters, The engine-factory element
- httpj:threadingParameters, The engine element, Configuring the thread pool
- maxThreads, Configuring the thread pool
- minThreads, Configuring the thread pool
- httpj:threadingParametersRef, The engine element
- httpj:tlsServerParameters, The engine element
- httpj:tlsServerParametersRef, The engine element
I
- Import-Package, Specifying imported packages
- inFaultInterceptors, Configuring an endpoint's interceptor chain
- inInterceptors, Configuring an endpoint's interceptor chain
- InOrder, Message delivery assurance policies
- install-component, Installing a component
- sm.host, Installing a component
- sm.install.file, Installing a component
- sm.password, Installing a component
- sm.port, Installing a component
- sm.username, Installing a component
- install-shared-library, Installing a shared library
- sm.host, Installing a shared library
- sm.install.file, Installing a shared library
- sm.password, Installing a shared library
- sm.port, Installing a shared library
- sm.username, Installing a shared library
- installing components, Installing a component, Installing a component
J
- Java Management Extenstions, JMX
- java.util.Map, Defining the property map
- JBI clustering, Overview
- JBI wrapper, Using the JBI wrapper, Using the JBI wrapper
- jbi-install-component, Installing a component
- failOnError, Installing a component
- file, Installing a component
- host, Installing a component
- password, Installing a component
- port, Installing a component
- username, Installing a component
- jbi-install-shared-library, Installing a shared library
- failOnError, Installing a shared library
- file, Installing a shared library
- host, Installing a shared library
- password, Installing a shared library
- port, Installing a shared library
- username, Installing a shared library
- jbi-shut-down-component, Shutting down a component
- failOnError, Shutting down a component
- host, Shutting down a component
- name, Shutting down a component
- password, Shutting down a component
- port, Shutting down a component
- username, Shutting down a component
- jbi-start-component, Starting a component
- failOnError, Starting a component
- host, Starting a component
- name, Starting a component
- password, Starting a component
- port, Starting a component
- username, Starting a component
- jbi-stop-component, Stopping a component
- failOnError, Stopping a component
- host, Stopping a component
- name, Stopping a component
- password, Stopping a component
- port, Stopping a component
- username, Stopping a component
- jbi-uninstall-component, Removing a component
- failOnError, Removing a component
- host, Removing a component
- name, Removing a component
- password, Removing a component
- port, Removing a component
- username, Removing a component
- jbi-uninstall-shared-library, Removing a shared library
- failOnError, Removing a shared library
- host, Removing a shared library
- name, Removing a shared library
- password, Removing a shared library
- port, Removing a shared library
- username, Removing a shared library
- jbi.xml, Contents of a file component service unit, Contents of a JMS service unit, Contents of a file component service unit
- jca-consumer, Types of consumer endpoints
- activationSpec, Procedure
- connectionFactory, Procedure
- destination, Configuring a destination
- destinationChooser, Determining the reply destination, Configuring an endpoint to use a destination chooser
- destinationName, Configuring a destination
- destinationResolver, Configuring an endpoint to use a destination resolver
- endpoint, Procedure
- marshaler, Configuring the consumer
- pubSubDomaim, Procedure
- replyDeliveryMode, Setting the reply message's persistence
- replyDestination, Determining the reply destination
- replyDestinationName, Determining the reply destination
- replyExplicitQosEnabled, Enforcing the configured values
- replyPriority, Setting the reply message's priority
- replyProperties, Setting custom JMS header properties
- replyTimeToLive, Setting a reply message's lifespan
- resourceAdapter, Procedure
- service, Procedure
- stateless, Activating statefullness
- storeFactory, Configuring the datastore
- targetEndpoint, Specifying the target endpoint
- targetInterface, Specifying the target endpoint
- targetService, Specifying the target endpoint
- JdbcStore, Configuring the datastore
- JdbcStoreFactory, Configuring the datastore
- jee:environment, Spring JEE JNDI lookup
- jee:jndi-lookup, Spring JEE JNDI lookup
- id, Spring JEE JNDI lookup
- jndi-name, Spring JEE JNDI lookup
- Jencks AMQPool (see AMQPool)
- JMS
- specifying the message type, Specifying the message type
- JMS destination
- specifying, Specifying the JMS address
- jms:address, Specifying the JMS address
- connectionPassword attribute, Specifying the JMS address
- connectionUserName attribute, Specifying the JMS address
- destinationStyle attribute, Specifying the JMS address
- jmsDestinationName attribute, Specifying the JMS address
- jmsiReplyDestinationName attribute, Using a Named Reply Destination
- jmsReplyDestinationName attribute, Specifying the JMS address
- jndiConnectionFactoryName attribute, Specifying the JMS address
- jndiDestinationName attribute, Specifying the JMS address
- jndiReplyDestinationName attribute, Specifying the JMS address, Using a Named Reply Destination
- jms:client, Specifying the message type
- messageType attribute, Specifying the message type
- jms:JMSNamingProperties, Specifying JNDI properties
- jms:server, Specifying the configuration
- durableSubscriberName, Specifying the configuration
- messageSelector, Specifying the configuration
- transactional, Specifying the configuration
- useMessageIDAsCorrealationID, Specifying the configuration
- JMSConfiguration, Specifying the configuration
- JmsConsumerMarshaler, Implementing the marshaler
- JMSDeliveryMode, Setting the reply message's persistence, Setting a message's persistence
- JMSExpirary, Setting a reply message's lifespan, Setting a message's life span
- JMSPriority, Setting the reply message's priority, Setting a message's priority
- JmsProviderMarshaler, Implementing the marshaler
- JmsSoapConsumerMarshaler, Overview
- JmsSoapProviderMarshaler, Overview
- JMX, JMX
- JNDI
- specifying the connection factory, Specifying the JMS address
- JndiObjectFactoryBean, Spring JNDI Templates
- JndiTemplate, Spring JNDI Templates
L
- listener container
- LockManager, Overview
- getLock(), Implementing a lock manager
- implementing, Implementing a lock manager
- lockManager, Configuring the endpoint to use a lock manager
- logical part, The logical part
M
- map, Defining the property map
- marshaler, Configuring an endpoint to use a file marshaler, Configuring the consumer
- marshaling
- binary files, Provided file marshalers
- flat files, Provided file marshalers
- Maven archetypes, Useful Maven archetypes
- Maven tooling
- adding the bundle plug-in, Adding a bundle plug-in
- binding component, JBI components
- component bootstrap class, JBI components
- component implementation class, JBI components
- component type, JBI components
- JBI component, JBI components
- project creation, Creating a JBI Maven project
- service engine, JBI components
- servicemix-jms-consumer-endpoint, Using the Maven JBI tooling
- servicemix-jms-provider-endpoint, Using the Maven JBI tooling
- set up, Setting up the Maven tools, Setting up the Maven tools
- shared libraries, Shared libraries
- maxLength, Maximum length of an RM sequence
- maxUnacknowledged, Maximum unacknowledged messages threshold
- MemoryStore, Configuring the datastore
- message element, WSDL elements, Defining Logical Messages Used by a Service
- message exchange patterns, Message exchange patterns
- in-only, Message exchange patterns
- in-optional-out, Message exchange patterns
- in-out, Message exchange patterns
- robust-in-only, Message exchange patterns
- message persistence, Setting the reply message's persistence, Setting a message's persistence
- message priority, Setting a message's priority
- message selectors, Using message selectors
N
- named reply destination
- specifying in WSDL, Specifying the JMS address
- using, Using a Named Reply Destination
- namespace, Namespace, Namespace
O
- operation element, WSDL elements
- outFaultInterceptors, Configuring an endpoint's interceptor chain
- outInterceptors, Configuring an endpoint's interceptor chain
P
- part element, Defining Logical Messages Used by a Service, Message parts
- element attribute, Message parts
- name attribute, Message parts
- type attribute, Message parts
- passWord, Configuring WS-persistence
- persistence, Setting the reply message's persistence, Setting a message's persistence
- poller, Configuration element
- archive, Archiving files
- autoCreateDirectory, Directory handling
- delay, Scheduling the first poll
- deleteFile, File retention
- endpoint, Identifying the endpoint
- file, Specifying the message source
- filter, Configuring an endpoint to use a file filter
- firstTime, Scheduling the first poll
- lockManager, Configuring the endpoint to use a lock manager
- marshaler, Configuring an endpoint to use a file marshaler
- period, Configuring the polling interval
- recursive, Directory handling
- service, Identifying the endpoint
- targetEndpoint, Specifying the target endpoint
- targetInterface, Specifying the target endpoint
- targetService, Specifying the target endpoint
- poller endpoint, Overview
- port element, WSDL elements
- portType element, WSDL elements, Port types
- priority, Setting a message's priority
- Private-Package, Specifying private packages
- provider, Component roles, Types of providers
- busCfg, Specifying the configuration to load
- connectionFactory, Procedure
- deliveryMode, Setting a message's persistence
- destination, Configuring a destination
- destinationChooser, Configuring a destination, Configuring the response destination, Configuring an endpoint to use a destination chooser
- destinationName, Configuring a destination
- destinationResolver, Configuring an endpoint to use a destination resolver
- endpoint, Procedure
- explicitQosEnabled, Enforcing configured values
- generic, Types of providers
- jms102, Procedure
- marshaler, Configuring the provider
- messageIdEnabled, Message IDs
- messageTimeStampEnabled, Time stamps
- mtomEnabled, Configuring an endpoint to support MTOM
- priority, Setting a message's priority
- pubSubDomaim, Procedure
- recieveTimeout, Configuring the timeout interval
- replyDestination, Configuring the response destination
- replyDestinationName, Configuring the response destination
- service, Procedure
- soap, Types of providers
- stateless, Activating statefullness
- storeFactory, Configuring the datastore
- timeToLive, Setting a message's life span
- useJbiWrapper, Turning of JBI wrapper processing
- wsdl, Specifying the WSDL
- provider endpoint, Overview
- connection factory, Procedure
R
- readMessage(), Implementing a file marshaler
- replyProperties, Setting custom JMS header properties
- RMAssertion, WS-Policy RMAssertion Children
- RPC style design, Message design for integrating with legacy systems
S
- sender, Configuration element
- append, Appending data
- autoCreateDirectory, Directory creation
- directory, Specifying the file destination
- endpoint, Identifying the endpoint
- marshaler, Configuring an endpoint to use a file marshaler
- service, Identifying the endpoint
- tempFilePrefix, Temporary file naming
- tempFileSuffix, Temporary file naming
- sender endpoint, Overview
- Sequence, How WS-RM works
- sequence element, Complex type varieties
- SequenceAcknowledgment, How WS-RM works
- service assembly, Packaging
- seeding, Seeding a project using a Maven artifact
- specifying the service units, Specifying the target components
- service consumer, Component roles
- service element, WSDL elements
- service engine, Component types
- service provider, Component roles
- service unit, Packaging
- seeding, Seeding a project using a Maven artifact
- specifying the target component, Specifying the target components
- service unit life-cycle, Managing service units
- shutdown-component, Shutting down a component
- sm.component.name, Shutting down a component
- sm.host, Shutting down a component
- sm.password, Shutting down a component
- sm.port, Shutting down a component
- sm.username, Shutting down a component
- SimpleFlatFileMarshaler, Provided file marshalers
- docElementname, Provided file marshalers
- insertLineNumbers, Provided file marshalers
- lineElementname , Provided file marshalers
- sm.component.name, Removing a component, Starting a component, Stopping a component, Shutting down a component
- sm.host, Installing a component, Removing a component, Starting a component, Stopping a component, Shutting down a component, Installing a shared library, Removing a shared library
- sm.install.file, Installing a component, Installing a shared library
- sm.password, Installing a component, Removing a component, Starting a component, Stopping a component, Shutting down a component, Installing a shared library, Removing a shared library
- sm.port, Installing a component, Removing a component, Starting a component, Stopping a component, Shutting down a component, Installing a shared library, Removing a shared library
- sm.shared.library.name, Removing a shared library
- sm.username, Installing a component, Removing a component, Starting a component, Stopping a component, Shutting down a component, Installing a shared library, Removing a shared library
- smx-arch, Seeding a project using a Maven artifact, Seeding a project using a Maven artifact
- SOAP 1.1
- endpoint address, SOAP 1.1
- SOAP 1.2
- endpoint address, SOAP 1.2
- soap-consumer, Types of consumer endpoints
- cacheLevel, Performace tuning using the listener container
- clientId, Performace tuning using the listener container
- concurrentConsumers, Performace tuning using the listener container
- connectionFactory, Procedure
- destination, Configuring a destination
- destinationChooser, Determining the reply destination, Configuring an endpoint to use a destination chooser
- destinationName, Configuring a destination
- destinationResolver, Configuring an endpoint to use a destination resolver
- durableSubscriberName, Using durable subscriptions
- endpoint, Procedure
- jms102, Procedure
- listenerType, Specifying an endpoint's listener container
- marshaler, Configuring the consumer
- maxMessagesPerTask, Performace tuning using the listener container
- messageSelector, Using message selectors
- pubSubDomaim, Procedure
- receiveTimeout, Performace tuning using the listener container
- recoveryInterval, Performace tuning using the listener container
- replyDeliveryMode, Setting the reply message's persistence
- replyDestination, Determining the reply destination
- replyDestinationName, Determining the reply destination
- replyExplicitQosEnabled, Enforcing the configured values
- replyPriority, Setting the reply message's priority
- replyProperties, Setting custom JMS header properties
- replyTimeToLive, Setting a reply message's lifespan
- serverSessionFactory, Configuring the server session listener container's session factory
- service, Procedure
- stateless, Activating statefullness
- storeFactory, Configuring the datastore
- subscriptionDurable, Using durable subscriptions
- targetEndpoint, Specifying the target endpoint
- targetInterface, Specifying the target endpoint
- targetService, Specifying the target endpoint
- transacted, Using transactions
- useJbiWrapper, Using the JBI wrapper
- validateWsdl, WSDL verification
- wsdl, Procedure
- soap-provider, Types of providers
- connectionFactory, Procedure
- deliveryMode, Setting a message's persistence
- destination, Configuring a destination
- destinationChooser, Configuring a destination, Configuring the response destination, Configuring an endpoint to use a destination chooser
- destinationName, Configuring a destination
- destinationResolver, Configuring an endpoint to use a destination resolver
- endpoint, Procedure
- explicitQosEnabled, Enforcing configured values
- jms102, Procedure
- marshaler, Configuring the provider
- messageIdEnabled, Message IDs
- messageTimeStampEnabled, Time stamps
- priority, Setting a message's priority
- pubSubDomaim, Procedure
- recieveTimeout, Configuring the timeout interval
- replyDestination, Configuring the response destination
- replyDestinationName, Configuring the response destination
- service, Procedure
- stateless, Activating statefullness
- storeFactory, Configuring the datastore
- timeToLive, Setting a message's life span
- useJbiWrapper, Using the JBI wrapper
- validateWsdl, WSDL verification
- wsdl, Procedure
- soap12:address, SOAP 1.2
- soap:address, SOAP 1.1
- Spring map, Defining the property map
- start-component, Starting a component
- sm.component.name, Starting a component
- sm.host, Starting a component
- sm.password, Starting a component
- sm.port, Starting a component
- sm.username, Starting a component
- stop-component, Stopping a component
- sm.component.name, Stopping a component
- sm.host, Stopping a component
- sm.password, Stopping a component
- sm.port, Stopping a component
- sm.username, Stopping a component
T
- time to live, Setting a message's life span
- transactions, Using transactions
- types element, WSDL elements
U
- uninstall-component, Removing a component
- sm.component.name, Removing a component
- sm.host, Removing a component
- sm.password, Removing a component
- sm.port, Removing a component
- sm.username, Removing a component
- uninstall-shared-library, Removing a shared library
- sm.host, Removing a shared library
- sm.password, Removing a shared library
- sm.port, Removing a shared library
- sm.shared.library.name, Removing a shared library
- sm.username, Removing a shared library
- userName, Configuring WS-persistence
- util:map, Defining the property map
W
- wrapped document style, Message design for SOAP services
- writeMessage(), Implementing a file marshaler
- WS-Addressing
- WS-I basic profile, WSDL verification, WSDL verification
- WS-RM
- AcknowledgementInterval, Acknowledgement interval
- AtLeastOnce, Message delivery assurance policies
- AtMostOnce, Message delivery assurance policies
- BaseRetransmissionInterval, Base retransmission interval
- configuring, Configuring WS-RM
- destination, How WS-RM works
- driverClassName, Configuring WS-persistence
- enabling, Enabling WS-RM
- ExponentialBackoff, Exponential backoff for retransmission
- externaL attachment, External attachment
- initial sender, How WS-RM works
- InOrder, Message delivery assurance policies
- interceptors, Apache CXF WS-RM Interceptors
- maxLength, Maximum length of an RM sequence
- maxUnacknowledged, Maximum unacknowledged messages threshold
- passWord, Configuring WS-persistence
- rmManager, Children of the rmManager Spring bean
- source, How WS-RM works
- ultimate receiver, How WS-RM works
- url, Configuring WS-persistence
- userName, Configuring WS-persistence
- wsam:Addressing, Configuring an endpoint to use WS-Addressing
- WSDL design
- RPC style, Message design for integrating with legacy systems
- wrapped document style, Message design for SOAP services
- WSDL extensors
- jms:address (see jms:address)
- jms:client (see jms:client)
- jms:JMSNamingProperties (see jms:JMSNamingProperties)
- jms:server (see jms:server)
- wsrm:AcksTo, How WS-RM works
- wswa:UsingAddressing, Configuring an endpoint to use WS-Addressing
Legal Notice
Trademark Disclaimer
Legal Notice
Third Party Acknowledgements
- JLine (http://jline.sourceforge.net) jline:jline:jar:1.0License: BSD (LICENSE.txt) - Copyright (c) 2002-2006, Marc Prud'hommeaux
mwp1@cornell.edu
All rights reserved.Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:- Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
- Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
- Neither the name of JLine nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - Stax2 API (http://woodstox.codehaus.org/StAX2) org.codehaus.woodstox:stax2-api:jar:3.1.1License: The BSD License (http://www.opensource.org/licenses/bsd-license.php)Copyright (c) <YEAR>, <OWNER> All rights reserved.Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
- Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
- Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - jibx-run - JiBX runtime (http://www.jibx.org/main-reactor/jibx-run) org.jibx:jibx-run:bundle:1.2.3License: BSD (http://jibx.sourceforge.net/jibx-license.html) Copyright (c) 2003-2010, Dennis M. Sosnoski.All rights reserved.Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
- Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
- Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
- Neither the name of JiBX nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - JavaAssist (http://www.jboss.org/javassist) org.jboss.javassist:com.springsource.javassist:jar:3.9.0.GA:compileLicense: MPL (http://www.mozilla.org/MPL/MPL-1.1.html)
- HAPI-OSGI-Base Module (http://hl7api.sourceforge.net/hapi-osgi-base/) ca.uhn.hapi:hapi-osgi-base:bundle:1.2License: Mozilla Public License 1.1 (http://www.mozilla.org/MPL/MPL-1.1.txt)