Tag Archives: NetBeans

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.

Using file templates in NetBeans 6.0: Customizing author in generated files

Whenever you ask NetBeans to create a new file (such as Java class or interface or an XML file) for you, it internally uses respective file template to generate the file content for you. This is particularly useful as it relieves you from a need to write boilerplate text, that may in case of Java files include things like package name, class definition, basic documentation (including author name) or a license text.

If you want to see, how file templates look like, simply select “Tools”->”Templates” from a NetBeans menu. A dialog window opens, where you can browse for a particular file template responsible for the content generated in a certain type of file:

Code Templates Browser Dialog

By selecting a template and clicking on “Open in Editor” button you can view or edit the template in NetBeans Editor window. In this blog I will be working primarily with Java Class template, but modifications covered here are generic and affect other templates as well.

As the blog title suggests, I am going to customize author information that will be generated into all newly created (Java) files. First of all, lets have a look at how Java File template looks like:


<#assign licenseFirst = "/*">
<#assign licensePrefix = " * ">
<#assign licenseLast = " */">
<#include "../Licenses/license-${project.license}.txt">

<#if package?? && package != "">
package ${package};


/**
*
* @author ${user}
*/
public class ${name} {

}

As you can see, file template uses a simple scripting language that controls the code generation. Since we want to customize author name, there is a single line interesting for us:

* @author ${user}

Customizing the user name

Bad news first: in NB5.x it was possible to customize the user variable by string table via advanced options. This is however not possible in NB6.0 and I have filed a regression issue, so hopefully this will be fixed when NB6.0 is officially released.

Good news is, that there is a workaround. You just need to know that by default, the value of the user property is taken from Java user.name system property. So if you want to customize the author user name generated into the new files, simply customize this property when starting NetBeans with additional -J-Duser.name="Name Surname (name.surname at myemail.com)" command line argument. For instance, my line for starting NetBeans looks like this:

/opt/netbeans-$NB_VERSION/bin/netbeans -J-Duser.name="Marek Potociar (marek.potociar at sun.com)" --userdir $NB_USER_DIR

…as you can see, in my script I am also customizing the version of NetBeans and NetBeans user directory where NetBeans store all user configuration (such as opened projects, window settings, cached classes etc). This makes it easy for me to maintain several different environment configuration which is particularly useful as I am working on more than one project and each projects requires different setup. If you really want to customize only the user name, your startup command may look like this:

/opt/netbeans-6.0/bin/netbeans -J-Duser.name="Marek Potociar (marek.potociar at sun.com)"

Technorati:
,
,