Category Archives: Metro

Metro – Java SOAP Web Services Stack

It’s been a while…

… since I wrote my last blog. And it’s not because I would not have anything to write about, but because I was rather busy working on a new release of Metro. The new Metro 2.1 is currently in the in the late pre-release state and we are preparing to release soon.

Many things happened in the Metro project since the last Metro 2.0.1 release. Perhaps most notable are the two of them:

  1. Metro mavenization
  2. Metro project migration to a new Kenai infrastructure

Metro project migration

Although both changes do have a visible impact on the Metro users, the latter one is perhaps more apparent. The first change a user would notice is the new project URL. The Metro project URL has changed from https://metro.dev.java.net/ to http://metro.java.net/. It means that you no longer need to use HTTPS to access public project web pages and the content loads faster. Also, with the new infrastructure, it is possible to use “sticky” login, so that your login information is remembered and you are not required to log in again when you access a restricted java.net page e.g. the next day. For someone like me who works with java.net on a daily basis this is a huge improvement. Similar URI related change applies to Metro mailing lists. Please consult the new Metro mailing list addresses here: http://java.net/projects/metro/lists

Another very important change in the Metro project caused by the migration to the new infrastructure is a decision to abandon nowadays somewhat obsolete CVS version control system and switch to SVN instead. Thus the new way how to checkout Metro/WSIT sources is:

svn checkout https://svn.java.net/svn/wsit~svn/trunk/wsit

For further information about working with Metro sources, please consult the Metro contributors page.

I shall perhaps mention that we also considered switching to a DVCS (e.g. Mercurial, GIT) but then decided to take smaller steps at a time. We may still revisit this decision in the future based on the feedback we receive from users. Should you have an opinion on this (or any other Metro related) topic that you want to share with us, please send an email to the Metro users mailing list.

The last very important project migration related change that comes to my mind is the new issue tracker that we use for projects running on the new java.net infrastructure – JIRA. For more information how to access Metro related issues, please see our Metro Issue Trackers page. Since JIRA has lots of capabilities, in the future Metro releases we are considering using JIRA not only as an issue tracker but also as the main feature & task manager.

Metro mavenization

Along with the project migration to the new infrastructure, Metro mavenization is second biggest non-functional change. Over the time we have been receiving numerous user requests for a better support of Maven-based development model. Also internally, we were constantly fighting with introduction of a more rigorous release management process and the maintenance of ever larger set of dependencies and their respective versions. And since our main delivery vehicle which Metro integrates into — GlassFish — has also switched to Maven a while ago, it was only natural to follow the same direction. And so we did…

As of today, all the main Metro bundle build scripts have been mavenized. Additionally, workspace of the WSIT project has been thoroughly restructured and modularized basing the module structure mainly on the code relationship to different WS-* domains. It was not an easy task and it involved a lot of refactoring as well as introduction of several inter-module API layers to allow for cleaner separation of the inter-module dependencies. In the future, the idea is to complete the Metro project mavenization by mavenizing also the JAX-WS RI workspace, which is the last (standalone) piece that is yet to be mavenized. From the user perspective not having JAX-WS RI project mavenized is not a big deal though, because JAX-WS RI is internally consumed by Metro/WSIT and as such we were forced to fix all the dependency related issues in the Maven artifacts produced by non-Maven JAX-WS RI build process.

To learn more about how to work with the mavenized Metro binaries, kindly consult the recently updated Maven section of the Metro User Guide.

Few notes on new Metro features

Metro 2.1, when released, will be just a minor update over Metro 2.0 so one should not expect any radical changes. Still, when it comes to functionality, apart from the bug fixes and small improvements, there are two topics I would like to briefly mention here.

First of all, after (5 or so) years we are finally officially introducing full-featured support of clustered environments. This feature currently comes with soon to be released GlassFish 3.1. While Metro high availability and failover support does not directly depend on the GlassFish 3.1 HA infrastructure but rather on a thin layer of a platform-independent HA API, in Metro 2.1 release we did not spend any effort in testing or integration of our HA support with other containers. However when it comes to GlassFish 3.1, we have created a very comprehensive HA test suite to verify that Metro HA would work well within GlassFish.

Another big thing feature-wise in Metro 2.1 is a complete replacement of the WS-AtomicTransactions/Coordination (or in short WS-TX) implementation code. The new code is essentially a WS-TX implementation from the Oracle WebLogic Server retrofitted to use the specific Metro and GlassFish run-time APIs where necessary. This new implementation introduces support for standardized versions of the WS-TX specifications in Metro. At the same time, unfortunately, this is a breaking change in the Metro WS-TX implementation to certain extent (particularly in the from-Java EJB WS scenarios) as EJB-based web service endpoints annotated with just the standard JavaEE @TransactionAttribute annotation will not have the WS-TX support enabled by default as was the case with earlier Metro releases. Instead, a new Metro-specific annotation (which is yet to be documented in the Metro User Guide) was introduced to enable WS-TX support for the annotation-based EJB endpoints. We have decided to introduce a breaking change in this case since the old solution has issues with mapping between WS-AT policy expressions and EJB @TransactionAttribute annotation values as well as it seems to complicate CTS testing. Yet, the main message for Metro users is that after quite a long break (caused mainly by the resourcing constraints) we have made a major improvement in the area of WS-TX support in Metro and we are finally on par with the latest WS-TX standards.

Metro v2.0 has been released

A new version of the open-source Java web services stack Metro v2.0 has been released today. This new release brings several notable new features, such as Configuration Management (check the short info), Persistent RM, experimental Declarative tubeline assembler (see here) as well as new enhancements in WS-Security, Trust and SecureConversation areas.

For the full documentation of all Metro features check the Metro user guide. Metro v2.0 runs on Tomcat, GlassFish V2 and is also shipped with GlassFish V3 — the first application server to support Java EE 6 — which was, same as Metro v2.0, released today.

Metro Reliable Messaging Configuration Summary

I finally found time to write up a summary of all features that can be configured in Metro Reliable Messaging. Please check the tables bellow. Enjoy… :-)

RM Configuration Namespace

PrefixNamespace
wsphttp://www.w3.org/ns/ws-policy
wsrmp10http://schemas.xmlsoap.org/ws/2005/02/rm/policy
wsrmphttp://docs.oasis-open.org/ws-rx/wsrmp/200702
net30rmphttp://schemas.microsoft.com/net/2005/02/rm/policy
net35rmphttp://schemas.microsoft.com/ws-rx/wsrmp/200702
sunrmphttp://sun.com/2006/03/rm
sunrmcphttp://sun.com/2006/03/rm/client
metrohttp://java.sun.com/xml/ns/metro/ws-rx/wsrmp/200702
This table contains XML namespaces used in WS-Policy assertions that are used to configure Metro Reliable Messaging

Reliable Messaging Configuration

Feature nameDescriptionWS-RM 1.0 compatible assertionWS-RM 1.1+ compatible assertion
Enable Reliable Messaging + version Specifies that WS-ReliableMessaging protocol MUST be used when sending messages.
Defines also the version of the WS-RM protocol to be used.
/wsrmp10:RMAssertion/wsrmp:RMAssertion
Sequence Inactivity Timeout Specifies the time interval beyond which either RM Source or RM Destination may
terminate the RM sequence due to inactivity. The default setting is 600,000 milliseconds
(10 minutes). A web service endpoint will always terminate session whose inactivity
timeout has expired. Specified in milliseconds.
/wsrmp10:RMAssertion/wsrmp10:InactivityTimeout/net35rmp:InactivityTimeout
Acknowledgement interval Specifies the duration after which the RM Destination will transmit an acknowledgement.
If omitted, there is no implied value. Specified in milliseconds.
/wsrmp10:RMAssertion/wsrmp10:AcknowledgementInterval/net35rmp:AcknowledgementInterval
Retransmission Interval Specifies how long the RM Source will wait after transmitting a message and before
retransmitting the message. If omitted, there is no implied value. Specified in
milliseconds.
/wsrmp10:RMAssertion/wsrmp10:BaseRetransmissionInterval
/sunrmcp:ResendInterval
/metro:RetransmissionConfig/metro:Interval
Retransmission Interval Adjustment Algorithm Specifies that the retransmission interval will be adjusted using a specific
(e.g. exponential back-off) algorithm.

/wsrmp10:RMAssertion/wsrmp10:ExponentialBackoff

("Exponential backoff" algorithm only)

/metro:RetransmissionConfig/metro:Algorithm
Maximum Retransmission Count


A message is considered to be transferred if its delivery at the recipient
has been acknowledged by the recipient.


If an acknowledgment has not been received within a certain amount of time
for a message that has been transmitted, the infrastructure automatically
retransmits the message. The infrastructure tries to send the message for
at most a preconfigured number of times. Not receiving an acknowledgment
before this limit is reached is considered a fatal communication failure,
and causes the RM session to fail.

N/A/metro:RetransmissionConfig/metro:MaxRetries
Close sequence timeout By default, the call to proxy.close() will not return until all messages have been
acknowledged. RM close timeout is the interval (in milliseconds) that the client
runtime will block waiting for a call to close() to return. If there are still
unacknowledged messages after this interval is reached, and the call to close
has returned, an error will be logged about messages being lost.

/sunrmcp:CloseTimeout

(client side only)

/metro:CloseSequenceTimeout
Acknowledgement request interval Defines the suggested minimum time that the sender (RM Source) should allow to elapse
between sending consecutive Acknowledgement request messages to the RM Destination.
/sunrmcp:AckRequestInterval/metro:AckRequestInterval
Bind RM sequence to security token Defines the requirement that an RM Sequence MUST be bound to an explicit token that is
referenced from a wsse:SecurityTokenReference in the CreateSequence message.
N/A/wsrmp:RMAssertion/wsp:Policy/wsrmp:SequenceSTR
Bind RM sequence to secured transport Defines the requirement that an RM Sequence MUST be bound to the session(s) of the underlying
transport-level protocol used to carry the CreateSequence and CreateSequenceResponse message.
(When present, this assertion MUST be used in conjunction with the sp:TransportBinding assertion.)
N/A/wsrmp:RMAssertion/wsp:Policy/wsrmp:SequenceTransportSecurity
Exactly once delivery Each message is to be delivered exactly once; if a message cannot be delivered then an error
MUST be raised by the RM Source and/or RM Destination. The requirement on an RM Source is that
it SHOULD retry transmission of every message sent by the Application Source until it receives
an acknowledgement from the RM Destination. The requirement on the RM Destination is that it
SHOULD retry the transfer to the Application Destination of any message that it accepts from
the RM Source until that message has been successfully delivered, and that it MUST NOT deliver
a duplicate of a message that has already been delivered.
default/wsrmp:RMAssertion/wsp:Policy/wsrmp:DeliveryAssurance/wsp:Policy/wsrmp:ExactlyOnce
At Most once delivery Each message is to be delivered at most once. The RM Source MAY retry transmission of unacknowledged
messages, but is NOT REQUIRED to do so. The requirement on the RM Destination is that it MUST filter
out duplicate messages, i.e. that it MUST NOT deliver a duplicate of a message that has already been
delivered.
N/A/wsrmp:RMAssertion/wsp:Policy/wsrmp:DeliveryAssurance/wsp:Policy/wsrmp:AtMostOnce
At Least once delivery Each message is to be delivered at least once, or else an error MUST be raised by the RM Source
and/or RM Destination. The requirement on an RM Source is that it SHOULD retry transmission of
every message sent by the Application Source until it receives an acknowledgement from the
RM Destination. The requirement on the RM Destination is that it SHOULD retry the transfer to the
Application Destination of any message that it accepts from the RM Source, until that message
has been successfully delivered. There is no requirement for the RM Destination to apply
duplicate message filtering.
/sunrmcp:AllowDuplicates/wsrmp:RMAssertion/wsp:Policy/wsrmp:DeliveryAssurance/wsp:Policy/wsrmp:AtLeastOnce
InOrder delivery Messages from each individual Sequence are to be delivered in the same order they have been sent
by the Application Source. The requirement on an RM Source is that it MUST ensure that the ordinal
position of each message in the Sequence (as indicated by a message Sequence number) is consistent
with the order in which the messages have been sent from the Application Source. The requirement
on the RM Destination is that it MUST deliver received messages for each Sequence in the order
indicated by the message numbering. This DeliveryAssurance can be used in combination with any
of the AtLeastOnce, AtMostOnce or ExactlyOnce assertions, and the requirements of those assertions
MUST also be met. In particular if the AtLeastOnce or ExactlyOnce assertion applies and the
RM Destination detects a gap in the Sequence then the RM Destination MUST NOT deliver any subsequent
messages from that Sequence until the missing messages are received or until the Sequence is closed.
/sunrmp:Ordered/wsrmp:RMAssertion/wsp:Policy/wsrmp:DeliveryAssurance/wsp:Policy/wsrmp:InOrder
Flow Control Enables or disables the flow control feature. When enabled, this feature works in conjunction with
the Max Buffer Size setting to determine the maximum number of messages for sequence that can be
stored at the endpoint awaiting delivery to the application. Messages may have to be withheld from
the application if ordered delivery is required and some of their predecessors have not arrived. If
the number of stored messages reaches the threshold specified in the Max Buffer Size setting, incoming
messages belonging to the sequence are ignored.
/net30rmp:RmFlowControl/net30rmp:RmFlowControl
Maximum Flow Control Buffer Size If Flow control is enabled, this value specifies the number of request messages that will be
buffered in the RM session. The default setting is 32. For more information, see the description
of the Flow Control option.
/net30rmp:RmFlowControl/net30rmp:MaxReceiveBufferSize/net30rmp:RmFlowControl/net30rmp:MaxReceiveBufferSize
Maximum concurrent RM sessions Specifies how many concurrently active RM sessions (measured based on inbound RM sequences) the SequenceManager
dedicated to the WS Endpoint accepts before starting to refuse new requests for sequence creation.
N/A/metro:MaxConcurrentSessions
Reliable Messaging Persistence Specifies whether the runtime should use persistent sequence and message storage or not.
N/A/metro:Persistent
Sequence manager maintenace task execution period Specifies the period (in milliseconds) of a sequence maintenance task execution. Sequence maintenance
task takes care of terminating inactive sequences and removing the terminated sequences from the
sequence repository.
N/A/metro:MaintenanceTaskPeriod
This table contains summary information about all features that can be configured within Metro Reliable Messaging domain

This information is now available via official Metro User Guide too.