Marek Potociar's Blog

10Dec/090

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.

Tagged as: , , , , No Comments
19Oct/097

Intercepting web service calls with a custom Metro Tube

In this blog, I am going to show you how to write a custom tube for intercepting web service messages and how to configure Metro to route all the web service traffic through this custom tube.

As you may know, the upcoming Metro v2.0 release will quietly introduce a new "Declarative tubeline assembler" feature that lets advanced Metro users to write their own Tubes and specify custom tubelines for web services in their applications. The reason why we are not advertising this feature is that we feel there's still some important work to be done in terms of consolidating all existing Metro configuration files and stabilizing some internal APIs enough to expose them publicly. So, before I continue with the blog that is clearly targeted at developers who like to live on the edge of new technologies, I need to clearly state the following "Safe Harbor" Statement:

Metro APIs discussed in this blog post are internal to Metro, evolving and may change in the future Metro releases without a prior warning. Use it at your own risk.

Good, so now that you have been properly warned (and scared), we can finally continue. As I have said, Metro 2.0 has this notion of declarative approach to assembling the web service processing tubeline, which you can imagine as a set of low-lever (and thus powerful) filters that are applied to each SOAP request/response that flows to/from a web service endpoint or its client. The standard set of tubes that comes with Metro takes care for all run-time processing including security, reliability, transactions, message validation, XML-Java and Java-XML transformations, business logic invocation etc.

The concept of tubes has been there in Metro for a quite a long time now. And, as I mentioned before, the concept is VERY powerful - many times more powerful than the standard JAX-WS handlers. Leveraging this concept at a user level was however difficult as there was no easy way how to insert a custom tube into a web service endpoint tubeline and thus effectively override the default Metro tubeline. The declarative tubeline assembler has changed that. It is now possible to write your own tube factories and use them in customizing the processing tubeline on the endpoint level basis. Let's have a look at one of the potential use cases.

In this use case, I am about to develop an interceptor capable of intercepting all calls to all web service endpoints deployed on the application server instance regardless of the application in which they are deployed. I am using GlassFish v2 with latest build of Metro v2.0 installed on it.

I will start with a simple "echo" test service application. By invoking this service I will be able to verify that my interceptor kicks in and really works. The code of the service is pretty simple and straightforward:

@WebService()
public class Echo {
 
    /**
     * Web service operation
     */
    @WebMethod(operationName = "echoMessage")
    public String echoMessage(@WebParam(name = "message")
    final String message) {
        return "Echoed: " + message;
    }
}

Once the service is deployed I can create the client application to invoke it. I am using NetBeans web project and for simplicity I embed the service invocation code directly to the index.jsp page. The code looks like this:

<html>
    <head>
        <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
        <title>JSP Page</title>
    </head>
    <body>
        <h1>Hello World!</h1>
        <%-- start web service invocation --%><hr/>
        <%
                try {
                    com.sun.metro.samples.tubeinterceptor.testservice.EchoService service = new com.sun.metro.samples.tubeinterceptor.testservice.EchoService();
                    com.sun.metro.samples.tubeinterceptor.testservice.Echo port = service.getEchoPort();
 
                    String result = port.echoMessage("Hello");
 
                    out.println("Result = " + result);
                } catch (Exception ex) {
                    out.println("Exception = " + ex.toString());
                }
        %>
        <%-- end web service invocation --%><hr/>
    </body>
</html>

When I select "Run" from the client's project context menu, the project gets deployed and the index page gets displayed with the result of invocation:

Echo Test Service Client Invocation

So far, it is a simple WS sample, nothing new, nothing special. Let's start with the interesting stuff then - I am going to create a new project containing my interceptor.

To intercept the Metro messages, first I need to create a custom implementation of the JAX-WS Tube interface. I will extend my implementation from AbstractFilterTubeImpl class. This class provides some common logic and provides default implementations for methods in the Tube interface. In my implementation I am just adding some logging messages that inform that the interceptor has been invoked. Here's the code:

final class InterceptorTube extends AbstractFilterTubeImpl {
    private static final Logger logger = Logger.getLogger(InterceptorTube.class.getName());
 
    static enum Side {
        Client,
        Endpoint
    }
 
    private final Side side;
 
    private InterceptorTube(InterceptorTube original, TubeCloner cloner) {
        super(original, cloner);
 
        this.side = original.side;
    }
 
    @Override
    public InterceptorTube copy(TubeCloner cloner) {
        return new InterceptorTube(this, cloner);
    }
 
    InterceptorTube(Tube tube, Side side) {
        super(tube);
 
        this.side = side;
    }
 
    @Override
    public NextAction processRequest(Packet request) {
        // TODO: place your request processing code here
        logger.info(String.format("Message request intercepted on %s side", side));
 
        return super.processRequest(request);
    }
 
    @Override
    public NextAction processResponse(Packet response) {
        // TODO: place your response processing code here
        logger.info(String.format("Message response intercepted on %s side", side));
 
        return super.processResponse(response);
    }
 
    @Override
    public NextAction processException(Throwable throwable) {
        // TODO: place your error processing code here
        logger.info(String.format("Message processing exception intercepted on %s side", side));
 
        return super.processException(throwable);
    }
 
    @Override
    public void preDestroy() {
        try {
            // TODO: place your resource releasing code here
        } finally {
            super.preDestroy();
        }
    }
}

Of course, your interceptor can do something really fancy with the intercepted messages; it can filter or modify the payload, process message headers, add new message headers, change or fork processing flow, your imagination is the only limit.

The next step is to implement a new TubeFactory class that will be used by Metro run-time code to instantiate my InterceptorTube during the tubeline creation. Again, here's the code:

public class InterceptorTubeFactory implements TubeFactory {
    private static final Logger logger = Logger.getLogger(InterceptorTubeFactory.class.getName());
 
    public Tube createTube(ClientTubelineAssemblyContext context) throws WebServiceException {
        logger.info("Creating client-side interceptor tube");
 
        return new InterceptorTube(context.getTubelineHead(), InterceptorTube.Side.Client);
    }
 
    public Tube createTube(ServerTubelineAssemblyContext context) throws WebServiceException {
        logger.info("Creating server-side interceptor tube");
 
        return new InterceptorTube(context.getTubelineHead(), InterceptorTube.Side.Endpoint);
    }
}

Normally, you would probably want to implement some logic that would decide whether or not the tube should be created, based on a presence of a particular WebServiceFeature or any other information from the tubeline assembly context, but in this scenario it is sufficient to just create a new interceptor tube whenever the factory method is invoked.

Now having both - tube and its factory - in place, I need to wire them with the Metro run-time. First of all, I have to create a custom metro.xmlconfig file that includes my interceptor tube factory and place it under META-INF directory inside my interceptor library jar. The easiest way to do that is to copy and modify the default Metro config file (metro-default.xml) which resides in webservices-rt.jar. Here's the resulting config file:

<metro  xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
   xmlns='http://java.sun.com/xml/ns/metro/config'
   version="1.0">
    <tubelines default="#intercepted-tubeline">
        <tubeline name="intercepted-tubeline">
            <client-side>
                <tube-factory className="com.sun.xml.ws.assembler.jaxws.TerminalTubeFactory" />
                <tube-factory className="com.sun.xml.ws.assembler.jaxws.HandlerTubeFactory" />
                <tube-factory className="com.sun.xml.ws.assembler.jaxws.ValidationTubeFactory" />
                <tube-factory className="com.sun.xml.ws.assembler.jaxws.MustUnderstandTubeFactory" />
                <tube-factory className="com.sun.xml.ws.assembler.jaxws.MonitoringTubeFactory" />
                <tube-factory className="com.sun.xml.ws.assembler.jaxws.AddressingTubeFactory" />
                <tube-factory className="com.sun.xml.ws.tx.runtime.TxTubeFactory" />
                <tube-factory className="com.sun.xml.ws.rx.rm.runtime.RmTubeFactory" />
                <tube-factory className="com.sun.xml.ws.rx.mc.runtime.McTubeFactory" />
                <tube-factory className="com.sun.xml.wss.provider.wsit.SecurityTubeFactory" />
                <tube-factory className="com.sun.xml.ws.rx.testing.PacketFilteringTubeFactory" />
 
                <tube-factory className="com.sun.metro.samples.tubeinterceptor.tube.InterceptorTubeFactory" />
 
                <tube-factory className="com.sun.xml.ws.dump.MessageDumpingTubeFactory" />
                <tube-factory className="com.sun.xml.ws.assembler.jaxws.TransportTubeFactory" />
            </client-side>
            <endpoint-side>
                <tube-factory className="com.sun.xml.ws.assembler.jaxws.TransportTubeFactory" />
                <tube-factory className="com.sun.xml.ws.dump.MessageDumpingTubeFactory" />
 
                <tube-factory className="com.sun.metro.samples.tubeinterceptor.tube.InterceptorTubeFactory" />
 
                <tube-factory className="com.sun.xml.ws.rx.testing.PacketFilteringTubeFactory" />
                <tube-factory className="com.sun.xml.wss.provider.wsit.SecurityTubeFactory" />
                <tube-factory className="com.sun.xml.ws.rx.mc.runtime.McTubeFactory" />
                <tube-factory className="com.sun.xml.ws.assembler.jaxws.AddressingTubeFactory" />
                <tube-factory className="com.sun.xml.ws.rx.rm.runtime.RmTubeFactory" />
                <tube-factory className="com.sun.xml.ws.tx.runtime.TxTubeFactory" />
                <tube-factory className="com.sun.xml.ws.assembler.jaxws.MonitoringTubeFactory" />
                <tube-factory className="com.sun.xml.ws.assembler.jaxws.MustUnderstandTubeFactory" />
                <tube-factory className="com.sun.xml.ws.assembler.jaxws.HandlerTubeFactory" />
                <tube-factory className="com.sun.xml.ws.assembler.jaxws.ValidationTubeFactory" />
                <tube-factory className="com.sun.xml.ws.assembler.jaxws.TerminalTubeFactory" />
            </endpoint-side>
        </tubeline>
    </tubelines>
 
</metro>

As you can see, I have inserted a reference to my custom tube factory into the chain of default Metro tube factories. The place of insertion depends on what you want to achieve and at what stage of processing you want to intercept. My factory is inserted very close to transport which lets my interceptor tube to see message in the same form as they are transferred over the wire. And now to the last piece. I want to make sure that Metro loads my config file for all web services in all applications deployed in the application server. Since Metro uses a classloader to load config files, I need to find a proper location where to put my library and perhaps modify the application server's classpath. As one may expect, the proper location for my library in GlassFish v2 is in ${AS_HOME}/lib, where the run-time Metro jar resides. Also I need to make sure that my jar gets loaded before Metro jars, so I need to update GlassFish classpath settings and add my library to the classpath prefix:

GlassFish v2 Admin Console Classpath Settings

And now I just properly configure the logging levels to be able to see the relevant logging messages in the server log...

com.sun.metro.samples.tubeinterceptor.tube -> INFO
javax.enterprise.resource.webservices.assembler -> FINER
javax.enterprise.resource.webservices -> INFO

...and restart the server. When I run the client again, in the server log I can see the following log messages which verify that my interceptor has been invoked for both, client and endpoint side in both request and response directions:

...
deployed with moduleid = TestServiceApp
Metro monitoring rootname successfully set to: com.sun.metro:pp=/,type=WSEndpoint,name=/TestServiceApp-EchoService-EchoPort
Default metro-default.xml configuration file located at: 'jar:file:/Users/m_potociar/dev/glassfish/glassfishv2-ur2/lib/webservices-rt.jar!/META-INF/metro-default.xml'
Application metro.xml configuration file located at: 'jar:file:/Users/m_potociar/dev/glassfish/glassfishv2-ur2/lib/InterceptorLib.jar!/META-INF/metro.xml'
Creating server-side interceptor tube
deployed with moduleid = TestClientApp
Trying to load 'metro-default.xml' via parent resouce loader 'com.sun.xml.ws.client.ClientContainer$1@13ffd111'
Default metro-default.xml configuration file located at: 'jar:file:/Users/m_potociar/dev/glassfish/glassfishv2-ur2/lib/webservices-rt.jar!/META-INF/metro-default.xml'
Trying to load 'metro.xml' via parent resouce loader 'com.sun.xml.ws.client.ClientContainer$1@13ffd111'
Application metro.xml configuration file located at: 'jar:file:/Users/m_potociar/dev/glassfish/glassfishv2-ur2/lib/InterceptorLib.jar!/META-INF/metro.xml'
Creating client-side interceptor tube
Message request intercepted on Client side
Message request intercepted on Endpoint side
Message response intercepted on Endpoint side
Message response intercepted on Client side
...

And that's it. I have successfully created and configured a custom interceptor tube that intercepts all web service message processing on the server. The sample ZIP containing all three NetBeans projects is available here.

Tagged as: , , , , , 7 Comments
20Aug/091

Off-line Metro installer for GlassFish v3

Right now Metro provides official off-line installation scripts for GlassFish v2 and Tomcat as part of the standalone Metro bundle. If you want to use latest Metro with GlassFish v3, you should update Metro installation via GlassFish v3 Update Center.

While updating Metro installation on GlassFish v3 via Update Center is really strongly encouraged and preferred way for most Metro users, there are cases when it would be really good to be able to update Metro on GlassFish v3 using an off-line installer. Off-line installer is especially helpful when trying to install Metro built from sources or trying to test latest nightly build of Metro that may not be available through the GlassFish v3 Update Center yet.

Unfortunately, there was no such installer available in the Metro bundle... until now. I have just added a first experimental version of such installer to the Metro workspace and it should be available for use with the Metro v2.0 nightly build tomorrow. Here's how to invoke the installer from the Bash command line, once you download and unpack the Metro bundle:

cd <metro-bundle-dir>
export AS_HOME=<gfv3-install-dir>/glassfish
ant -f metro-on-glassfish-v3.xml install

Simple, isn't it? For more information on the Ant targets available in the script file, just type

ant -f metro-on-glassfish-v3.xml help

I hope you will enjoy this small improvement, yet remember – this is an experimental installer, use it at your own risk. And don't forget to send me any issues you may encounter with the installer!

Tagged as: , 1 Comment
22Jun/090

GlassFish Day in Zurich, Switzerland

Today I presented project Metro at GlassFish Day event which took place in Zurich, Switzerland as part of the larger Jazoon 2009 conference. From what I can say the event was very successful. We had great speakers and I think that the whole event was very well attended and received.

Alexis did a great introduction by providing insight into where we are with GlassFish at present as well as where are we heading. In the second session he showcased clustering with GlassFish and the GlassFish Enterprise Manager - a really nice and useful tool that lets GlassFish administrators monitor various aspects of GlassFish instances and presents the collected data in a very comprehensible graphical ways - an ideal tool for all customers who "have more money than time".

The third morning session was dedicated to Roberto and his preview of the new features in the upcoming JavaEE 6 release. I think the guys in the JSR expert group did a really good job in making the enterprise java developer's life MUCH easier. The coming APIs seem to be very flexible and easy to use and learn. From what I can tell, this isn't "yet another update", this is probably the first JavaEE release where I have a good feeling about its completeness, flexibility and maturity. Great thing also is that this JavaEE release not only adds new stuff but it also recognizes obsolete technologies, which will be pruned and eventually removed from the specification. Among technologies currently on the prune list are JAX-RPC (hurray!), Entity EJBs (is there anyone brave enough still using them anyway?) and few others. These technologies either never really caught up or have already been practically replaced by their modern counterparts anyway. As for the features which I am particularly interested in and happy about are dependency injection specified by JSR 299 (Web Beans) and Servlet 3.0. Also I am very glad that JAX-RS - Java API for RESTful Web Services (JSR 311) made its way into JavaEE 6 as well.

The last session before lunch was my Metro talk. I provided a short overview of Metro, its features and architecture and dedicated most of the session to practical demonstrations including development of simple SOAP web service and client as well as few other demos showcasing advanced Metro features, such as message-level security, reliable messaging and streaming large data over SOAP web services.

After the lunch Alexis did his "GlassFish Survival Guide" talk focusing on installation, profiles, most useful administration commands as well as other useful tips which are good to know when starting with GlassFish. Those are the tips which can help you to avoid something I call unnecessary "aha!" moments and which can save you a lot of time.

In the next session, Jerome went through the new and noteworthy stuff coming in the planned GlassFish v3 release. This release, which is planned for September this year, is getting closer and closer and truly brings the next-generation GlassFish AS. The new application server - or "application container" would be probably more accurate - will be OSGi-fied, highly modular and extensible and will bring support for additional languages and frameworks, such as Ruby on Rails or Groovy. Those of you, who are interested in trying it out right now, you can download the latest GlassFish v3 Preview release - a really fancy name for a beta release, isn't it :-) .

After the interesting talk on the tooling support for JavaEE 6 features presented by Ludo and Roman came the last talk of the day - the one that I was eagerly awaiting - the talk on JSF 2.0 presented by Ed Burns. If there was ever an API that needed a major update it would definitely be JSF - this is not my sentence, I read it in some materials to the talk, but I absolutely agree :) And once again I was very pleasantly surprised by the new prospects that lie ahead of us in the space of this UI framework. The new single-file component definition which resembles Objective C object definition or revamped and standardized Ajax support are only few notable changes to mention.

It was a great session to end with the day full of new information. Overall today's GlassFish Day was a realy great kick-off for the Jazoon 2009 Conference that starts officially tomorrow. Looking forward to it - stay tuned for more details!

Tagged as: , , No Comments
   

Recent Posts

Topics

Tags

RSSMy tweets

Blogroll

Projects

Archives

Meta