Hi, Folks!

I know it’s been quite a while since I’ve last posted in here… lots of projects

As things are evolving on SOA, I would like to give my two cents here about SOA Architectures. So, just to begin the subject, I would like to introduce…

What is SOA?

SOA stands for Service-Oriented Architecture (as you probably know by now ). But, WTH is a service?

The efforts to define a service have gone really far, but no one seems to be able to really define a service. People are able to describe a service by how it should be, not by what it actually is. According to Thomas Erl (http://www.soaglossary.com/service_orientation.php), a service should:

• Have a standardized service contract
• Promote loose coupling
• promote abstraction
• be reusable
• be autonomous
• be stateless
• be discoverable
• be composable

OK, but what does it mean in terms of real-world services?

It means that you should design your services to be as granular as possible to promote composability and reusability. It also means that these services should be stateless (i.e., they should not assume that the server is in a state a previous request set it on); these services should be autonomous (i.e., they should not depend on other services to perform it’s actual task – unless, of course, we are talking about a composition); they should be discoverable (i.e., you should have some kind of directory where you can find the service that performs the task you are looking for); they should be loose coupled to each other; and last but not least, they should have a contract you can rely on – one that is standardized such as your clients will not have trouble when using your service.

Note that, so far, no one has talked about WS-* or REST. That’s because SOA is not defined in terms of technology, or tools, or whatever. SOA is based on a set of good practices, in order to ensure ROI (Return of Investment). BTW, of course SOA is not that cheap (studies prove that a brand new implementation of SOA is 30% more expensive in the initial phases, but they pay off over time).

But, getting back to technology… nor WS-* nor REST define SOA. You can have lots of WS-* Web Services on your architecture, or lots of REST services on your architecture, but still have no SOA. Again: SOA is based on practices, not technology. Of course, enterprises over the world have developed tools to help achieve the goals (some of them don’t even give so much help ;)), but the tools are not the end – they are the means.

If you define your architecture such as enough business logic is exposed as services (again, no one is talking about technology here), then you will have SOA.

Buuuut… here comes the little lines at the bottom.

Why my company always talk about technology and vendors when it comes to SOA?

The truth is that it can be very hard to promote SOA within the terms mentioned above (or, at least, to do so without tools). That’s why companies almost always have SOA with WS-* and tooling. It’s really hard to have directories of services without any kind of tools, and it’s very hard to promote service discovery without WSDL’s (OK, REST has got WADL, but it hasn’t got to a level where every REST service has one. Actually, REST doesn’t need WADL, and that’s not the case with WS-* services).

Also, even that your company decides to make its own tooling to promote these practices, it can be very hard as well to comply with non-functional requirements, such as performance, monitorability, scalability, etc. Remember that these services are granular, and that the traffic over network is XML/JSON. Imagine lots of services doing marshalling / unmarshalling of these data everywhere.

So, the first tool that came around to solve these problems is the ESB.

WTH is an ESB?

ESB stands for Enterprise Service Bus. As the name says, it is nothing but a bus to your services. But, wait… a bus that takes what to what?

The responsability of an ESB is to map requests from a client (usually, these clients see a service, with a contract and everything else) to… somewhere. Really, the ESB may lead to a WS-*, a REST service, the file system, BPEL (I’ll talk about this one later), JMS, and lots of other protocols. Actually, it should be able to transform any protocol to any protocol. But, of course, this very core of an ESB may lead to accomplish several other purposes. Take monitorability, for example: if an ESB will map these protocols, and data will pass through it, it may take metrics over it, and map response times, success rate, failure rates, fire alerts when these metrics reach a given threshold, and so on. Also, it may guarantee security to these services (by exposing only the ESB for clients, and inserting some assertions to routings), as well as several other things.

Also, an ESB may promote security by an application level. They usually have a feature known as throttling, which prevents a client from sending too much data (so much it can cause service failure). Of course, these kind of stuff should be ensured within XML Schemas, but they know detailed schemas are hard to maintain inside an ecosystem of dozens, hundreds or even thousands of web services.

But what an ESB does not do is to recompose requests. Remember service composability? That’s not the function of an ESB (although some of them even do it). Service composability requires a more business-oriented tool, something like…

BPEL

BPEL stands for Business Process Execution Language. It is the industry’s standard for composing workflows, made of several web service calls. What it does is not only the workflow, but handling of several issues, like:

• expose the composition as a web service itself;
• rolling back of failed transactions (known as compensatory transactions);
• keeping the state of transactions, both in case of server failure as for auditing;
• optimizing the calls to the several web services it may compose;
• keeping the flow visual, i.e., to ease the development and/or auditing.

As you may have realized, BPEL is specialized in keeping state of stuff. I know, web services should be stateless, and BPEL is – from the point of view of the client. But it keeps the state of the compositions for more pragmatic stuff like the mentioned above. It is conceptually different from an ESB as ESB’s should not keep the state of the requests, anywhere.

So, how to organize these together?

A good architecture should leverage all non-functional requirements and, at the same time, be able to change whenever it is needed. It’s a bit hard to talk about this subject in a single blog post, but within the mentioned features above, a good architecture could be like this:

As the picture doesn’t make justice to the thought, let me explain it:

As an ESB does every kind of transformation, protocol A -> protocol B (doesn’t mean, of course, that A is different from B), it is fair to place all data traffic over it, just to place metrics, alerts, throttling, and everything else, onto it. BPEL, WS-* services, REST services, and so on, will be accessible through it, and BPEL will not see directly the other services, but will reference the services that are already placed inside the ESB.

Of course this architecture has a huge drawback: too much overhead inside one piece. The ESB, here, must be intensively took care of (I hope your company has some baby sitters! =D). It means that maybe a few network cards, some gigabytes of RAM, and clustered to some four, five nodes. But believe me, depending on the number of services your company has (maybe the very size of the company), it totally pays off. Of course, maybe does not make sense if you have only a few services, but I’m talking here of a few hundreds (or thousands) of services.

Conclusion

You should not believe a single word that’s written here =D (Just kidding!)

Architectures don’t come inside a box. You need to be very very extra judiciously to analyze whether you need to place these kind of stuff in your company. Perhaps you don’t really need BPEL. Perhaps you don’t really need an ESB at all. Perhaps you need it but you can’t afford it. Perhaps it makes more sense having REST services than WS-* and these bunch of stuff. Every single aspect of SOA comes with positives and negatives. What you need to do is to analyze these points and carefully think if you really need the positives and if you can handle the negatives.

The project is built with Maven and Eclipse, sou you may be able to checkout it and import it on your Eclipse (or other environments compatible with Eclipse, like Netbeans).

It is configured with:

Spring and Spring Security 3.0.5
Jersey 1.9
Hibernate 3.4.0
JPA 1.0
MySQL 5.1

If you want a different configuration, feel free to modify it as you wish and, if you don’t mind, please take a few minutes to update the repository. By the way, it is https://github.com/alesaudate/kickstart-springjerseyhibernate. Feel free to clone it and have a bootstrap on your project.

Enjoy!

• A properly installed SOA Suite , 11g (I´m not gonna show here how to install it, but there are plenty of good stuff on this subject on the web);
• A JDeveloper 11g with SOA Extensions enabled
• A test tool named SOAP UI

So, let´s do it: start your SOA Suite and JDeveloper. Once your JDeveloper is open, right-click the applications area, as shown in the figure:

Then, select the menu “SOA Tier” and the SOA Project:

Select your project´s name and the project technology (in our case, SOA):

Create your project using Composite with BPEL (as it should be just a simple BPEL project; some day I will explain here what the other types are):

Select the synchronous template and mark the “expose as a SOAP service” checkbox:

Then, you should see something similar to the image:

Click on the assign component and drag it to the diagram. You see highlighted positions; they are places where you can drop the component:

Place the assign in the proper position:

Then, double click the just-placed component. You should see an image similar to the next one:

Click the ‘plus’ icon and you will see the following options:

Once doing so, click the “copy operation” option. You should see the following screen:

Expand both sides until you see the following screen (you should select the options, too):

Then, click OK. You will get back to the previous screen. Select the “general” tab and change the name of the operation to “AssignEcho”, like the screen:

Click OK and you will get back to the BPEL Designer screen. Now, it´s time to deploy our process. Right-click your project, and you should see a menu like the following:

As you maybe don´t have a connection in place, select the “new connection” option. Then, follow the wizard:

I´m assuming here that your username is weblogic (and you know the password as well):

Also, I´m assuming here that your SOA Suite is loaded on localhost, port 7001 (or 7002 if it´s SSL), with a domain loaded to soa_domain. They are the defaults.

Then, click “test connection”. If everything is OK, you should see the “8 of 8 tests succesful” status message.

Click OK and, once again, you will get back to the BPEL Designer screen. Now, your new connection should be available on the connections list:

Click the newly-created connection and you should see the deploy screen:

While deploying, it should ask for username and password:

Then, access the Enterprise Manager site (for me, it is available on http://localhost:7001/em). Once inputting the username and password, you should see the following screen:

Expand the selections according to the image and select your newly-deployed project:

If you click the “test” button, you should see a screen like this:

Personally, I don´t like using the enterprise manager to test my services, for personal reasons. So, I´d rather using SOAP UI. Select the WSDL of your service and then, create a project in SOAP UI, like this one:

Once doing so, SOAP UI will create a screen like the following (if everything is OK, change the interrogation sign for “hello, world!” or anything like this):

If everything is OK, then you should see a screen like this:

And that´s it! Your BPEL Process is working, as it is echoing every phrase you input to it. If you want to go further, try to explore the Assign component and the others, to improve your knowledge.

See ya!

The flow is like that: the dangerous operation has the fuse as a shell. The first state, “closed fuse”, has a counter of failed invocations and a threshold. When the client produces an invocation, it allows the invocation to pass through. If the call succeeds, then resets the counter. If it fails, increment the counter. If the counter reaches the threshold, it disables the fuse, going to the “open fuse” state. This state has a variable that represents an ammount of time and another one representing the moment in time when it has become the active state. Any call to the dangerous operation in this state will cause it to fail without even invoking the operation. When it is in this state for the amount of time specified in the variable, it decides that the call deserves another chance. So the invocation goes to the “half open fuse”. This state tries to invoke the operation again. If it fails, go to the open state again, resetting the timer. If it succeeds, go to the closed state again, resetting the counter of failed invocations.

OK, nice pattern, but what does it have to do with SOA?

The magic in this pattern (and the whole book) is that it brings light to subjects that most developers don´t give enough attention. One of these subjects is that you cannot rely on the network. Final. I have never seen any thrustable network (and I believe you haven´t, too!), so, as long as SOA is a kind of distributed architecture that relies on the network and we cannot rely on the network, so we can´t rely on services either! So, as long as services are unthrustable, we can apply this pattern, to:

• Ensure that we won´t get stuck waiting for services that might never return;
• Ensure that, if the server that is holding the web service is drowning from lots of invocations, at least we are not the ones that are gonna disable it for good;
• And many many other good reasons to do so. Read the book

As Michael himself doesn´t give any hints on the implementation of such a pattern, I decided to implement it, and you can download it from the downloads section. It is very simple, as it doesn´t allow only web services to be invoked via the pattern, but any other kind of dangerous operation too. You can modify the code the way you want to achieve your desire. My hint is that, allied to stuff like AOP and interceptors in general, you may do it the ultimate solution to never, ever have this kind of problem again.

Cheers!

When not: If your team does not know REST, maybe it´s not a good idea to use it in development, because REST has its own culture – Uniform Interfaces, Hypermedia, the concept of Resource-Oriented, etc.

How:

BaseEntity.java

package com.alesaudate.domain;

import javax.persistence.GeneratedValue;
import javax.persistence.GenerationType;
import javax.persistence.Id;
import javax.persistence.MappedSuperclass;
import javax.persistence.Version;

import org.hibernate.validator.ClassValidator;
import org.hibernate.validator.InvalidValue;


@MappedSuperclass
public abstract class BaseEntity {
	
	@Id
	@GeneratedValue(strategy=GenerationType.AUTO)
	private Long id;
	
	@Version
	private Long version;

	public Long getId() {
		return id;
	}

	public void setId(Long id) {
		this.id = id;
	}

	public Long getVersion() {
		return version;
	}

	public void setVersion(Long version) {
		this.version = version;
	}
	
	
	
	/**
	Validation code, that is valid for all subclasses.
	*/
	public void validate () throws ValidationException {
	
		ClassValidator validator = new ClassValidator(getClass());		
		
		InvalidValue[] invalidValues = validator.getInvalidValues(this);
		
		if (invalidValues != null && invalidValues.length > 0) {
			throw new ValidationException(buildValidationExceptionMessage(invalidValues));
		}
	}
	
	
	public String buildValidationExceptionMessage (InvalidValue[] invalidValues) {
		StringBuilder builder = new StringBuilder();
		
		for (InvalidValue value : invalidValues) {
			builder.append(value.toString()).append("\n");
		}
		
		return builder.toString();
	}
	
}

BaseService.java

package com.alesaudate.services;

import java.util.ArrayList;
import java.util.List;

import javax.ws.rs.DELETE;
import javax.ws.rs.GET;
import javax.ws.rs.POST;
import javax.ws.rs.PUT;
import javax.ws.rs.Path;
import javax.ws.rs.PathParam;
import javax.ws.rs.Produces;
import javax.ws.rs.core.MediaType;

import org.hibernate.criterion.DetachedCriteria;
import org.hibernate.criterion.Restrictions;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.orm.hibernate3.HibernateTemplate;
import org.springframework.stereotype.Component;
import org.springframework.transaction.annotation.Transactional;

import com.alesaudate.domain.BaseEntity;
import com.alesaudate.domain.InvalidStateException;
import com.alesaudate.domain.Person;
import com.alesaudate.services.support.collections.Collection;



@Component
public abstract class BaseService<T extends BaseEntity> {
	
	
	@Autowired
	private HibernateTemplate hibernateTemplate;
	
	
	@Transactional
	public T createOnDatabase (T entity) throws InvalidStateException {
		entity.validate();
		getHibernateTemplate().persist(entity);
		return entity;
	}
	
	
	@POST
	@Produces({MediaType.TEXT_XML, MediaType.APPLICATION_XML})
	public T create (T entity) throws InvalidStateException {
		return createOnDatabase(entity);
	}
	
	
	@Transactional
	public T updateOnDatabase (T entity) throws InvalidStateException {
		entity.validate();
		getHibernateTemplate().update(entity);
		return entity;
	}
	
	@PUT
	@Produces({MediaType.TEXT_XML, MediaType.APPLICATION_XML})
	public T update (T entity) throws InvalidStateException  {
		return updateOnDatabase(entity);
	}
	
	
	@Transactional(readOnly=true)
	public T findOnDatabase (Long id) {
		
		DetachedCriteria criteria = DetachedCriteria.forClass(getManagedClass()).add(Restrictions.eq("id", id));
		List entities = getHibernateTemplate().findByCriteria(criteria);
		if (entities.isEmpty()) 
			return null;
		return (T)entities.get(0);
	}
	
	@GET
	@Path("{id}")
	@Produces({MediaType.TEXT_XML, MediaType.APPLICATION_XML})
	public T find (@PathParam("id")Long id) {
		T entity = findOnDatabase(id);
		loadEntity(entity);
		return entity;
	}
	
	
	@Transactional(readOnly=true)
	public List<T > findAllFromDatabase () {
		
		DetachedCriteria criteria = DetachedCriteria.forClass(getManagedClass());
		List<T> all = getHibernateTemplate().findByCriteria(criteria);
		loadList(all);
		return all;
	}
	
	@GET	
	@Produces({MediaType.TEXT_XML, MediaType.APPLICATION_XML})	
	@Collection
	public List<T> findAll() {
		return findAllFromDatabase();
	}
	
	
	@Transactional
	public void deleteFromDatabase (T toDelete) {
		getHibernateTemplate().delete(toDelete);
	}
	
	

	@DELETE
	@Produces({MediaType.TEXT_XML, MediaType.APPLICATION_XML})
	public void delete (T toDelete) {
		deleteFromDatabase(toDelete);
	}
	
	public abstract Class<? extends BaseEntity> getManagedClass();
	
	
	public abstract void loadEntity (T data);
	
	public abstract void loadList (java.util.Collection<T> data);
	
	
	public void setHibernateTemplate(HibernateTemplate hibernateTemplate) {
		this.hibernateTemplate = hibernateTemplate;
	}
	
	public HibernateTemplate getHibernateTemplate() {
		return hibernateTemplate;
	}

}

PersonService.java

package com.alesaudate.services;

import java.util.Collection;

import javax.ws.rs.Path;

import org.hibernate.criterion.DetachedCriteria;
import org.hibernate.criterion.Restrictions;
import org.springframework.stereotype.Component;
import org.springframework.transaction.annotation.Propagation;
import org.springframework.transaction.annotation.Transactional;

import com.alesaudate.domain.Address;
import com.alesaudate.domain.BaseEntity;
import com.alesaudate.domain.Person;




@Component
@Path("/person")
public class PersonService extends BaseService<Person>{

	@Override
	public Class<? extends BaseEntity> getManagedClass() {
		return Person.class;
	}

	@Override
	public void loadEntity(Person data) {
		//Load addresses
		data.getAddresses();
	}

	@Override
	@Transactional(propagation=Propagation.MANDATORY)
	public void loadList(Collection<Person> data) {
		for (Person p : data) {			
			getHibernateTemplate().find("select p.addresses from Person p");
			for (Address address : p.getAddresses()) {
				getHibernateTemplate().evict(address);
				address.makeXMLCompatible();
			}
			getHibernateTemplate().evict(p);
		}
		
	}

	
	
	
	
	
	
}

applicationContext.xml:

<?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:context="http://www.springframework.org/schema/context"
	xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
		http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context-3.0.xsd">

	

	<context:component-scan base-package="com.alesaudate.services" />

<!-- Other bean definitions... -->		


</beans>

web.xml

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://java.sun.com/xml/ns/javaee" xmlns:web="http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd" xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd" id="WebApp_ID" version="2.5">
  <display-name>Architecture</display-name>
  
  <context-param>
       <param-name>contextConfigLocation</param-name>
       <param-value>classpath:applicationContext.xml</param-value>
   </context-param>

 
   <listener>
          <listener-class>org.springframework.web.context.ContextLoaderListener</listener-class>
   </listener>
   <listener>
          <listener-class>org.springframework.web.context.request.RequestContextListener</listener-class>
   </listener>

 <servlet>
 	<servlet-name>Jersey Servlet</servlet-name>
 	<servlet-class>com.sun.jersey.spi.spring.container.servlet.SpringServlet</servlet-class>
 </servlet>
 
 <servlet-mapping>
 	<servlet-name>Jersey Servlet</servlet-name>
 	<url-pattern>/*</url-pattern>
 </servlet-mapping>
  
</web-app>

End.

Hi! Today, I´m gonna show you how to develop a simple SSL web service. Please note that this is not a “enterprise” way of developing a secure web service, but this may be very useful for testing purposes.

Constraints

To develop this service, you need to use a Sun/Oracle JVM (I tested with 1.6 VM, but should work with 1.5, too). This is not gonna work in any other kind of VM. Also, you need to have JAX-WS in your classpath.

The code

The code begins with the development of the web service itself. I used a standard JAX-WS service as an example, so my service looks like this:

@WebService
public class SOAPService {

	public String test() {
		return "Hello, SSL world!";
	}	
}

Next, we may use Java´s Endpoint class to create our object as an web service. The code is like

Endpoint endpoint = Endpoint.create(new SOAPService());

At this point, you need to create the server, and to create the server, you need a .jks (Java Keystore) file. You may create this file using JDK´s (or JRE´s) tooling, but I prefer using a GUI to do so. Personally, I like Lazgo´s KeyStore Explorer (available here). I won´t get in details here on how to create the JKS file; if you don´t know how to do it, you may want to have a look here.

Note: be aware that the CN attribute of your certificate must be equal to your host´s name!

After creating the JKS file, we are ready to create our HTTPS server. I won´t explain this code very much, as it should be pretty self-explanatory:

public static void main(String[] args) throws Exception {
		Endpoint endpoint = Endpoint.create(new SOAPService());
		SSLContext ssl =  SSLContext.getInstance("SSLv3");
		
		
		KeyManagerFactory kmf = KeyManagerFactory.getInstance(KeyManagerFactory.getDefaultAlgorithm()); 
		KeyStore store = KeyStore.getInstance(KeyStore.getDefaultType());


		//Load the JKS file (located, in this case, at D:\keystore.jks, with password 'test'
		store.load(new FileInputStream("D:\\keystore.jks"), "test".toCharArray()); 

		//init the key store, along with the password 'test'
		kmf.init(store, "test".toCharArray());
		KeyManager[] keyManagers = new KeyManager[1];
		keyManagers = kmf.getKeyManagers();
		
		

		//Init the trust manager factory
		TrustManagerFactory tmf = TrustManagerFactory.getInstance(TrustManagerFactory.getDefaultAlgorithm());

		//It will reference the same key store as the key managers
		tmf.init(store);
		
		TrustManager[] trustManagers = tmf.getTrustManagers();
		
		
		ssl.init(keyManagers, trustManagers, new SecureRandom());

		//Init a configuration with our SSL context
		HttpsConfigurator configurator = new HttpsConfigurator(ssl);
		

		//Create a server on localhost, port 443 (https port)
		HttpsServer httpsServer = HttpsServer.create(new InetSocketAddress("localhost", 443), 443);
		httpsServer.setHttpsConfigurator(configurator);
		
		
		//Create a context so our service will be available under this context
		HttpContext context = httpsServer.createContext("/test");
		httpsServer.start();
		

		//Finally, use the created context to publish the service
		endpoint.publish(context);
		
		

	}

And voilà! That should be enough to your service be available under SSL. With this code, the wsdl of the service should be available under https://localhost:443/test?wsdl.

Please note that, at the time that I developed this service, I had some trouble with the generated WSDL, specifically with the port address and references to schema files. A reasonable work around for this problem (if you have it too) is to download the files (WSDL, schemas, and so on) and fix it by hand.

See ya!

I know that you always say, first, what I need to know…

That´s right. First of all, be aware that I tested it with EJB´s services, and I don´t know if it works with other types of exposed web services. Also, note that I present here a solution that works with annotated web services.

Ok, show me the solution

Step #1: Annotate your web service´s class with @HandlerChain:

package com.alesaudate.webservices;

@WebService
@HandlerChain(file="handlers.xml") //Here, you need to reference a configuration file. In this case, it got to be in the same package as the class
public class MyService {

//...


}

Step #2: Create a configuration file, like:

<?xml version="1.0" encoding="UTF-8"?>
<jws:handler-chains xmlns:jws="http://java.sun.com/xml/ns/javaee">

  <jws:handler-chain>
    <jws:handler>
      <jws:handler-name>MimeHandler</jws:handler-name>
      <jws:handler-class>com.alesaudate.webservices.MimeTypeHandler</jws:handler-class>      
    </jws:handler>
</jws:handler-chain>
  
</jws:handler-chains>

(Note that it need to be named “handlers.xml”, as referenced in the annotation)

Step #3: Create a interceptor for the class:

package com.alesaudate.webservices;

import java.util.Set;

import javax.xml.namespace.QName;
import javax.xml.soap.SOAPException;
import javax.xml.soap.SOAPMessage;
import javax.xml.ws.handler.MessageContext;
import javax.xml.ws.handler.soap.SOAPHandler;
import javax.xml.ws.handler.soap.SOAPMessageContext;

public class MimeTypeHandler implements SOAPHandler<SOAPMessageContext>{

	public Set<QName> getHeaders() {
		return null;
	}

	public void close(MessageContext context) {
		
	}

	public boolean handleFault(SOAPMessageContext context) {
		return true;
	}

	public boolean handleMessage(SOAPMessageContext context) {
		try {
                                          context.getMessage().getMimeHeaders().setHeader("Content-Type", "text/xml");
		} catch (SOAPException e) {
			throw new RuntimeException(e);
		}
		return true;
	}
	

}

Pretty easy, right? I´m taking for granted that the interceptor and the configuration file are pretty self-explanatory, but if you have any doubts, don´t hesitate asking me, OK?

Bye!

So, give me a brief description on what it is about.

People who are used to work with SOA are, usually, used to work with ESB´s – I say “ESB´s”, plural, to mean different kinds from different vendors of ESB – and BPEL. ESB´s are often used to justify decoupling of clients from service providers. I think it is great, but people usually forget that ESB´s, as long as they are too decoupled from the system, do not provide so much advantages as it should. So, usually, ESB´s are a layer of extra complexity to systems (the exception are some odd situations that don´t fit the usual description). Sometimes, you need some piece of software that is more intimate to the system, that can interact in an easier way to the system (like some easy way to audit calls, log them, place warns on whether systems are responding or not – therefore avoiding issues on being overloaded due to slow responsiveness of external services -, etc.). So, thinking about it, I developed this pattern.

Explain it better, what is it about?

People need to be in control of their applications. People should be in control of their applications. Usually, that´s not what happens to a SOA-based app, because we rely too much on external tools and forget that good things may be done at home, too. So, you don´t need to use a service composition to audit external services I/O, for example. If you would do so by today´s standards, you would build a service to do the auditing, then group the external service and the audit service into one piece of service composition, then offer the composition´s contract to the client… too much work. You should not build separate services unless you need them as services (after all, SOA is about getting the IT to work along with the business, right? So, it should not try to add extra pieces of complexity, like one more service, to the business, right?); so, you should approach the problem with another solution, like intercepting the messages according to your programming language way of doing so.

So, my pattern is about intercepting outgoing messages / incoming responses by building transparent, language-friendly units, in a manner that, if you need extra capabilities but do not want (or do not need) to build extra services, you should consider applying this pattern.

How to do it?

First, you should take the original WSDL and override it, replacing the original address – a technique shown here. I´m gonna call this service “shell service”, from now on. The shell service´s purpose is to provide the capability of adding this extra logic, which means it should be built in the main programming language you use in your application. To build it, you should use the same logic as the mentioned post, but should modify the provider to something like the following:

package com.alesaudate.webservices;

import javax.xml.soap.SOAPMessage;
import java.net.URL;
import java.util.Iterator;
import javax.xml.namespace.QName;
import javax.xml.ws.Dispatch;
import javax.xml.ws.Service;


public class SOAPProvider {

	public Dispatch<SOAPMessage> getDispatcher (String wsdl, String namespace, String servicename, String portName){

		try {
			//create a representation of the service
			Service service = Service.create(new URL(wsdl), new QName(
					namespace, servicename));

			final Iterator<QName> ports = service.getPorts();

			QName methodToBeCalled = null;

			//Select the port to be called
			if (portName == null)
				methodToBeCalled = ports.next();

			else {
				while (methodToBeCalled == null || !methodToBeCalled.getLocalPart().equals(portName)) {
					methodToBeCalled = ports.next();
				}
			}

			//Create the dispatcher, given the data.
			Dispatch<SOAPMessage> dispatch = service.createDispatch(
					methodToBeCalled, SOAPMessage.class, Service.Mode.MESSAGE);

			return dispatch;
		} catch (Exception e) {
			throw new RuntimeException("Error calling web-service", e);
		}
	}
}

package com.alesaudate.webservices;

import javax.xml.soap.SOAPMessage;
import javax.xml.ws.Provider;
import javax.xml.ws.ServiceMode;
import javax.xml.ws.WebServiceProvider;
import javax.xml.ws.Service.Mode;

@ServiceMode(Mode.MESSAGE)
@WebServiceProvider(portName="blogSOAP",
		serviceName="blogService",
		targetNamespace="http://alesaudate.com/webservices",
		wsdlLocation="WEB-INF/wsdl/blog.wsdl")
public class MySOAPProvider implements Provider<SOAPMessage>{


	public static final String ORIGINAL_WSDL = "http://localhost/SampleService?wsdl";
	public static final String ORIGINAL_SERVICE = "sampleService";
	public static final String ORIGINAL_PORT = "samplePort";
	public static final String ORIGINAL_NAMESPACE = "sampleNamespace";

	private SOAPProvider provider;
	
	public MySOAPProvider() {
		this.provider = new SOAPProvider();
	}


	//You may add any extra logic here.
	@Override
	public SOAPMessage invoke(SOAPMessage request) {
		Dispatch<SOAPMessage> dispatcher = provider.getDispatcher(ORIGINAL_WSDL, ORIGINAL_NAMESPACE , ORIGINAL_SERVICE,ORIGINAL_PORT);
		SOAPMessage response = dispatcher.invoke(request);
		return response;
	}

}

Just to remind the reader, I would like to mention that this technique has been shown here.

Conclusion

I have shown here a design pattern that I call Services Mediator. Basically, it is the same that an Enterprise Service Bus does, but with the difference that it must be implemented in the same language that the application uses, providing, then, more control to the application programmer. So, at any time the services need some business logic, but does not necessarily need to use services to do so, the programmer may add this logic inside the services shell.

• An Apache Tomcat (or any Application Server that is compatible with JAX-WS)
• A JAX-WS runtime (I used the RI, that I got from here – most application servers already have)

Now, as it is a contract-first web service, we need the contract. I used this one:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<wsdl:definitions xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:tns="http://alesaudate.com/webservices" xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" name="blog" targetNamespace="http://alesaudate.com/webservices">
  <wsdl:types>
    <xsd:schema targetNamespace="http://alesaudate.com/webservices">
      <xsd:element name="operation">
        <xsd:complexType>
          <xsd:sequence>
            <xsd:element name="request" type="xsd:string"/>
          </xsd:sequence>
        </xsd:complexType>
      </xsd:element>
      <xsd:element name="operationResponse">
        <xsd:complexType>
          <xsd:sequence>
            <xsd:element name="response" type="xsd:string"/>
          </xsd:sequence>
        </xsd:complexType>
      </xsd:element>
    </xsd:schema>
  </wsdl:types>
  <wsdl:message name="operation">
    <wsdl:part element="tns:operation" name="parameters"/>
  </wsdl:message>
  <wsdl:message name="operationResponse">
    <wsdl:part element="tns:operationResponse" name="parameters"/>
  </wsdl:message>
  <wsdl:portType name="blog">
    <wsdl:operation name="blogOperation">
      <wsdl:input message="tns:operation"/>
      <wsdl:output message="tns:operationResponse"/>
    </wsdl:operation>
  </wsdl:portType>
  <wsdl:binding name="mySOAPBinding" type="tns:blog">
    <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
    <wsdl:operation name="blogOperation">
      <soap:operation soapAction="http://alesaudate.com/webservices/SampleOperation"/>
      <wsdl:input>
        <soap:body use="literal"/>
      </wsdl:input>
      <wsdl:output>
        <soap:body use="literal"/>
      </wsdl:output>
    </wsdl:operation>
  </wsdl:binding>
  <wsdl:service name="blogService">
    <wsdl:port binding="tns:mySOAPBinding" name="blogSOAP">
      <soap:address location="http://localhost:8080/WebServices/provider"/>
    </wsdl:port>
  </wsdl:service>
</wsdl:definitions>

Now, we must provide an implementation class (or, how I like to call, where the magic happens =P ). Here is my implementation:

package com.alesaudate.webservices;

import javax.xml.soap.SOAPMessage;
import javax.xml.ws.Provider;
import javax.xml.ws.ServiceMode;
import javax.xml.ws.WebServiceProvider;
import javax.xml.ws.Service.Mode;

@ServiceMode(Mode.MESSAGE)
@WebServiceProvider(portName="blogSOAP", 
		serviceName="blogService",  
		targetNamespace="http://alesaudate.com/webservices", 
		wsdlLocation="WEB-INF/wsdl/blog.wsdl")
public class MySOAPProvider implements Provider<SOAPMessage>{

	@Override
	public SOAPMessage invoke(SOAPMessage request) {
		try {
			request.writeTo(System.out);
		} catch (Exception e) {
			e.printStackTrace();
		} 
		return request;
	}

}

Please note that this refers to a WEB-INF directory. So, as you may have guessed by now, it MUST run on a web project (.war). Other forms of java files, like .jar or .ear are unable to run this code.

Now, we must provide what I call “the glue”: files that provide the binding. For the RI implementation, we must provide a file called sun-jaxws.xml and place it under the WEB-INF directory. For our project, it has the following structure:

<endpoints
    xmlns="http://java.sun.com/xml/ns/jax-ws/ri/runtime"
    version="2.0">

    <endpoint
        name="example"
        implementation="com.alesaudate.webservices.MySOAPProvider"
        wsdl="WEB-INF/wsdl/blog.wsdl"
        service="{http://alesaudate.com/webservices}blogService"
        port="{http://alesaudate.com/webservices}blogSOAP"
        url-pattern="/provider" />

</endpoints>

We also need to insert the right entries into web.xml:

<listener>
        <listener-class>com.sun.xml.ws.transport.http.servlet.WSServletContextListener</listener-class>
    </listener>
    <servlet>
        <servlet-name>provider</servlet-name>
        <servlet-class>com.sun.xml.ws.transport.http.servlet.WSServlet</servlet-class>
        <load-on-startup>1</load-on-startup>
    </servlet>
    <servlet-mapping>
        <servlet-name>provider</servlet-name>
        <url-pattern>/provider</url-pattern>
    </servlet-mapping>

The URL pattern, here, is the address where our web service will answer requests and will provide it´s contract.

Having reached this point so far, we need to place JAX-WS lib´s on the common library directory under Tomcat (for application servers like JBoss, you may skip this step).

And that´s all! Accessing the address http://localhost:8080/WebServices/provider?wsdl has shown me the WSDL that I quoted above, how about you?

You may check the code that I used here at the downloads section.

See ya!