Apache CXF Web Service Development book.

I was invited to review the new book about Apache CXF from packtpub, it is called《Apache CXF Web Service Development》by Naveen Balani and Rajeev Hathi. From the table of content, it covers both web service and restful service in CXF, also had three chapters for the CXF’s frontend, transport, interceptors, invoke etc, which are the essential concepts of CXF’s architecture. So it definitely seems interesting to me. I will post more detailed review once I finished the book.

Publishing web service in JBoss ESB

As of this writing, JBoss ESB 4.6 has two ways of publishing web service for ESB service.
1. Using JSR 181 annotation to do the web service publish and use SOAPProcessor action to connect it in ESB.
2. Providing the in,out, fault xsd schema to generate the wsdl dynamically and publish the web service.
These two ways are not exclusive, it is for different usage:
1. The first one is using JBossWS to publish the annotated Java service, and then using the SOAPProcessor to be a thin wrapper for the existed web service.
2. The second one, which we called EBWS(Endpoint Web Service), is asking developers to provide the in,out,fault xsd if it is required, And then uses these xsds, plus the service info (like service name, category etc) that were defined in the jboss-esb.xml to generate the wsdl and publish the web service.

The JBoss ESB distribution has both quick start examples for these two scenarios. We will examine them in order shortly, quickstart/webservice_producer sample is using the first approach that we’ve described, while the quickstart/publish_as_webservice is the EBWS as we said.

web service producer using SOAPProcessor

We will examine the first approach, below are the steps that is required to publish a web service in ESB.

1.Add the impl class with jsr 181 annotation
Lets see the GoodbyeWorldWS.java class, this is the class that is supposed to expose as web service.

@WebService(name = "GoodbyeWorldWS", targetNamespace="http://webservice_producer/goodbyeworld")
public class GoodbyeWorldWS {
@WebMethod
public String sayGoodbye(@WebParam(name="message") String message) {

   Message esbMessage = SOAPProcessor.getMessage();
   if(esbMessage != null) {
       System.out.println("**** SOAPRequest perhaps mediated by ESB:\n" + esbMessage.getBody().get());
   }
   System.out.println("Web Service Parameter - message=" + message);
   return "... Ah Goodbye then!!!! - " + message;
}
....
}

You can see that we are using the jsr181 annotation to expose it as web service. Noted that we are using the SOAPProcessor class to get the incoming soap message just for demonstration, you don’t have to use it in this class’s implementation.

2.Add web.xml to deploy it in servlet container
In the $webservice_producer/war/resources/WEB-INF/web.xml, it looks like
<servlet>

        <servlet-name>GoodbyeWorldWS</servlet-name>
   <servlet-class>org.jboss.soa.esb.samples.quickstart.webserviceproducer.webservice.GoodbyeWorldWS
</servlet>

<servlet-mapping>
   <servlet-name>GoodbyeWorldWS</servlet-name>
   <url-pattern>/GoodbyeWorldWS</url-pattern>
</servlet-mapping>

Typically, we can build a war file that includes both web.xml and the GoodbyeWorldWS.class, and it should be enough to be published as a web service through JBoss WS. since we are trying to access the web service through our ESB, so we need to define an extra file (jboss-esb.xml) in our case.

3.Add SOAPProcessor in the jboss-esb.xml
In the jboss-esb.xml service section, we need to use the SOAPProcessor as following:

<action name="JBossWSAdapter" class="org.jboss.soa.esb.actions.soap.SOAPProcessor">
<property name="jbossws-endpoint" value="GoodbyeWorldWS"/>
</action>

Here the “jbossws-endpoint” property should be referred to published web service servlet name.
*Tip: There’s one optional property “rewrite-endpoint-url” which is not used in this sample. This property is to support load balance on HTTP endpoints.

4.pack them in esb and war archive
The last step for us it to pack them and then deploy. The war file will include all needed classes and web.xml to publish web service. The esb file will include all needed esb files, like jboss-esb.xml etc. You can bundle the war file into esb archive, which is the way that sample uses.

Until now, we’ve described all of important steps. Next, we will deploy this esb archive into ESB server, you can see the wsdl file at: http://localhost:8080/contract/ (This is offered by ESB), or you can see the one from http://localhost:8080/jbossws/services, that is offered by JBoss WS.

5.Add the client to do the test
So, we’ve completed our server side work. In the example, we defined three gateway for this web service, for the simplicity, we will just look at the one uses JBR gateway to do the test in our client. Here is the client code:

   private void sendMessageToJBRListener(String protocol, int port, String message) throws Throwable {
   String locatorURI = protocol + "://localhost:" + port;
   InvokerLocator locator = new InvokerLocator(locatorURI);
   System.out.println("Calling JBoss Remoting Listener using locator URI: " + locatorURI);

   Client remotingClient = null;
   try {
       remotingClient = new Client(locator);
       remotingClient.connect();

       // Deliver the message to the listener...
       Object response = remotingClient.invoke(message);
       System.out.println("JBR Class: " + response.getClass().getName());
       System.out.println("Response from JBoss Remoting Listener '" + locatorURI + "' was '" + response + "'.");
   } finally {
       if(remotingClient != null) {
           remotingClient.disconnect();
       }
   }
}

We are using the following soap message in our client as input.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:good="http://webservice_producer/goodbyeworld">
<soapenv:Header/>
<soapenv:Body>
 <good:sayGoodbye>
    <message>Goodbye!!
 </good:sayGoodbye>
</soapenv:Body>
</soapenv:Envelope>

Run the “ant deploy” to deploy the server into ESB server; Run the ‘ant runtest’, you would get following result:

saygoodbye_over_http:
[echo] Invoking a JBossWS Endpoint over HTTP (via JBoss ESB).
[java] Calling JBoss Remoting Listener using locator URI: http://localhost:8765
[java] JBR Class: java.lang.String
[java] Response from JBoss Remoting Listener 'http://localhost:8765' was '<env:Envelope xmlns:env='http://schemas.xmlsoap.org/soap/envelope/'><env:Header></env:Header><env:Body><ns2:sayGoodbyeResponse xmlns:ns2="http://webservice_producer/goodbyeworld"><return>... Ah Goodbye then!!!! - Goodbye!!</return></ns2:sayGoodbyeResponse></env:Body></env:Envelope>'.

ESB End Point Web Service

Now, we will see the End Point Web Service, the corresponding example is publish_as_webservice in the JBoss ESB distribution. Lets also see it step by step.

1.The Web Service server class
firstly, take a look at the server impl class.

public class ESBWSListenerAction extends AbstractActionLifecycle
{
protected ConfigTree _config;

public ESBWSListenerAction(ConfigTree config)
{
   _config = config;
}

public Message displayMessage(Message message) throws Exception
{
.......
}

Is it just an ordinary ESB action? right, it is. This is totally different from the first one that we saw earlier, we do not have annotation, we used the ESB’s Message Object as input/output parameter.

* Note: In this approach, you can view it as Dispatch/Provider way that we used to have in JAX-WS, it means you deal with the raw soap message directly, the server doesn’t help you do the unmarshall work, this is also a very big difference from the first approach.

2. define request, response, fault xsd
In this example, we just define the in and out xsd. it is as following:
request.xsd

<xs:schema version="1.0" targetNamespace="http://www.jboss.org/sayHi" xmlns:x1="http://www.jboss.org/sayHi"  xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified">
<xs:element name="sayHi" type="x1:sayHi"/>
<xs:complexType name="sayHi">
<xs:sequence>
 <xs:element name="arg0" type="xs:string" minOccurs="1"/>
</xs:sequence>
</xs:complexType>
</xs:schema>

Response.xsd

<xs:schema version="1.0" targetNamespace="http://www.jboss.org/sayHi" xmlns:x1="http://www.jboss.org/sayHi"  xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified">
<xs:element name="sayHiResponse" type="x1:sayHiResponse"/>
<xs:complexType name="sayHiResponse">
<xs:sequence>
 <xs:element name="arg0" type="xs:string" minOccurs="0"/>
</xs:sequence>
</xs:complexType>
</xs:schema>

We won’t show the fault.xsd for the simplicity.

3. Add xsd file in the jboss-esb.xml
After we’ve defined the xsd file, we will add it in the jboss-esb.xml like following.

       <actions  inXsd="/request.xsd" outXsd="/response.xsd" faultXsd="/fault.xsd">
              <action name="action" class="org.jboss.soa.esb.samples.quickstart.publishAsWebservice.ESBWSListenerAction" process="displayMessage"/>
       </actions>

*Tip: Here it use the ‘service name’ + hard code name, like ‘Binding’ for binding, ‘Op’ for operation name in the generated wsdl. Refer to ESBServiceEndpointInfo class for its detail.

4.build it as an esb artifact and deploy
The last step is to build them as an esb archive and deploy it into the ESB server, as same as the first approach, you can see its wsdl file through either http://localhost:8080/contract or http://localhost:8080/jbossws/services.

The client is as same as the first one(apart from the soap message and url), so I won’t show it again.

Summary

You see two approaches to help you publish web service in JBoss ESB. At first glance, you might think EBWS(second approach here) is simple as you don’t need to build the war file etc. But I would say the first approach is more common in the real use case.

[Acknowledgement]
I’d like to thank my colleague Jim Ma for help me explain these two approaches on publishing web service.

[Reference]
1. JBoss ESB website.
2. JBoss ESB Webservice Producer.

SAML & XACML links

Some great SAML links.

1. SAML v2.0 Technical Overview (Strongly recommended)
2. Ensure portable trust with SAML from IBM developerworks
3. SAML 2.0 from wikipedia
4. Demystifying SAML from Oracle/BEA

XACML links:

1. Sun’s XACML Implementation Programmer’s Guide
2. Introduction to XACML
3. Control information access with XACML from IBM developerworks
4. XACML Tutorial with a Use Case Scenario for Academic Institutions by Hemant Goyal

JBoss SOA-P 4.3.GA released.

On 30th Oct, we’ve just released the SOA-P 4.3.GA, this version include a great improvements. Details you can see from here. Again, I just posted a chinese version of release announcement.

Conversation Pattern

Gregor says:

There’s usually a handful of roles that are defined. And usually there’s a series of message types, and that’s where WSDL and XSDs can do a little bit for us, like a certain message has a certain meaning and a certain structure. So for example I buy coffee and maybe my message contains what I want and then in the case of Starbucks there are 17 optional fields for all the extra double shot; but you have some notion of what’s in these messages and then you have the rules about which messages can flow in which order. And that is really the most difficult part.

And that is exactly the sort argument between the BEPL people – they say that most of the time there is a central coordinator and this works pretty well and it’s executable – and then what the choreography people say – careful here, you’re making a very strong assumption, really we should look at the overall conversation there could be 20 parties and they all send messages back and forth, now we should not assume that there is this one thing that controls everything. That’s exactly when the people fight and, stand up, and walk off with this kind of argument.

To the point. ;-), Hope you enjoy all the interview from Gregor Hohpe

"JBI in a nutshell" presentation

Today, I conduct a ‘JBI in a nutshell’ in our Beijing team, because we are trying to think how to make JBossESB SCA compatible. But before introduction of SCA, I’d like to share JBI spec to our team from my experience when I was working on ServiceMix. So here come the ‘JBI in a nutshell’ ppt that I used today.

Hopefully you will find it offers a little help for you understanding JBI, ServiceMix, and JBossESB.

service-based enterprise integration pattern made easy

A new artilce from Dr. Waseem Roshen, in the series titled: Services-based enterprise integration patterns made easy, it is quite interesting and easy-read to know the Enterprise Integration concepts. and also a little background.;)

Brief Introduction on the WS-CDL

Because of the work’s need, I need to work on the integration between the WS-CDL Tool and JBoss ESB, and here comes the chance that need to take a look at the WS-CDL specification.

Why the WS-CDL specification exists? what is it for? IMHO, now we have the WSDL as a contract to define the service in a language-independent way. we can consider the “interface” as a contract definition in the JAVA world. But we don’t have any thing to define the collaboration contract among multiple participants yet. Some people might say the UML Sequence diagram is a way to document it, but it lacks of the data description which has been used in the exchanges in the collaboration.

With the WS-CDL spec and its according tool, it can help us to design a system from top-down approach, well, it is sort of reminding me the era of MDA(Model Driven Architecture), personally, I am not a fan of MDA, that includes a lot of code generation. To some extent, WS-CDL is belong to the MDA, but as I said before, WS-CDL just defines the contract that multiple participants are working, it is not trying to describe everything in detail, so that you can build the whole system with one “Generate Code” click.

WS-CDL is mainly used for the Business Analyst. With current tools support, it can generate to WS-BPEL or Java skeleton code.

So, back to the WS-CDL specification itself, what is it composed of?

1. Collaborating Participants

• 1.1 RoleType — It defines the role, as the minimum unit for participants.
• 1.2 RelationshipType — It defines the relationship in roles.
• 1.3 ParticipantType — It is consist of one or multiple roles.
• 1.4 ChannelType — How and where participants collaborate.

2. Information Driven Collaborations

• 2.1 InformationType — described the type of information used, simple wrapper for xsd.
• 2.2 Variable
• 2.3 Expressions
• 2.4 Token and TokenLocator. (Tokens differ from variables in that variables contain values which MAY be populated as the result of actions or events within a choreography life-line whereas tokens contain information that define the piece of the data that is relevant.)
• 2.5 WorkUnit
• 2.6 Choreography
• 2.7 Choreography Life-line
• 2.8 Choreography Exception Handling
• 2.9 Choreography Finalization

3. Activities

3.1 Ordering Structures

• 3.1.1 Sequence
• 3.1.2 Parallel
• 3.1.3 Choice

3.2 Interacting

• 3.2.1 Interaction Based Information Alignment.

For full and detailed explanation please see WS-CDL specification.

Also, see Gregor’s Presentation at infoQ.

Links on WS-CDL.

Firstly, WS-CDL stands for Web Services Choreography Description Language.

1. An introduction & comparison between WS-CDL and WS-BPEL
2. WS-CDL spec
3. Two definition explanations on WS-CDL and WS-BPEL from John Reynolds. Also the two comments from Steve is very good.
4. An WS-CDL example illustration
5. Implementing WS-CDL essay

And if you want to know more about WS-CDL, then DO NOT miss below two links.
1) Pi4Tech Blog
2) Pi4.org

Update: Add the ‘implementing ws-cdl essay’ on Aug 4, 2008.

Links on WS-BPEL

1. WS-BPEL 2.0 Tutorial
2. WS-BPEL Specification