The Axis2 Transport Framework, Page 2
API of the Listener Manager
Listener manager provides the following APIs to mange transport listeners in a given system.
- init: To initialize the listener manager, you must create a configuration context and pass that as the method parameter. Inside the method, it will keep a reference to the configuration context and will set the listener manger field in the configuration context as the created listener manager.
- start: You can add any number of transport listeners in axis2.xml, but nothing will happen until you call this method. So, when you call the start method, it will take all the available transport listeners from axisConfiguration and then initialize and start that (will call the init and start methods, respectively).
- startSystem: You can just call startSystem rather than calling the two methods above. The inside method implementation will call the init and start methods.
- stop: This method can be used to stop all the listeners in the system.
- addListener: You can use this method to add a new listener into the system. When you add a listener, you have to pass two method arguments, the transport description object and boolean value. The transport description object has to have a transport listener in it, and the boolean value specifies whether the listener is running or not. If the boolean value is true, it will just add the listener into the list; otherwise, it will call both the init and start methods before adding them to the list. In the case of AxisServlet, it will use true as the boolean value because AxisServlet is running when it creates the listener manager.
- isListenerRunning: To check whether a given listener is up and running, if the listener is in the started listeners list, it will return true.
- getEPRforService: As discussed in the transport listener section, to get an EPR for a given service, listener manager itself provides an API to get the service EPR for a given service. The method takes two parameters, the name of the service and the name of the transport. Here the name of the service cannot be null but the name of the transport can be null. If the transport name is null, it will pick a transport from the started transport list and ask for the service EPR from that transport. Otherwise, if the transport name is not null, it will get the corresponding transport and ask the service EPR from that transport.
Note: In the case of Listener manager, all the transport receivers in the system share the same configuration context. The practical usage of this listener manager and its listeners is that one can expose same service using different transports or different addresses. A good use case could be publishing same service using HTTP, TCP, and SMTP. Isn't that cool?
The important thing in Axis2 is that it can receive a message via SMTP and a response can be send using HTTP. So, Axis2 can handle different transport combinations without having any problems. Figure 2 shows how Transport Listeners, Listener Manager, and Axis2 run time link together.
Figure 2: Listener Manager and Transport Listeners
Running a client inside a server using server's runtime
What does running a client inside a server mean?
Axis2 supports full asynchronous Web service invocation. There you can send the request in one transport and you can get the response via some other transport. In Axis2 terms, this is called send/receive non blocking using two channels. In this case, you have to have a running transport listener at the client side as well; otherwise, when someone asks to invoke two channels, the Axis2 invocation will start the corresponding transport receiver at the client side if that is present in the corresponding AxisConfiguration.
On the client side, when you create a ServiceClient, you can pass the configuration context, and when invoking a service client, you can use that configuration context as its runtime. The interesting thing is all the modules, service, properties, and transports that are available in that configuration context easily can be accessible by the service client.
When someone calls the init method of the listener manager, the corresponding field in the configuration context will be set. If the configuration context that passed to the service client does not have a listener manager object,a new one will be created and added into the configuration context and init the listener manager. Therefore, the service client always has a valid listener manager object in its configuration context.
When invoking a non-blocking, two-channel invocation, it first will try to find the incoming transport by using
String tarnsportName = Options.getTransportInProtocol();
and then take the listener manger and check whether the given listener is running. If so, it will ask the EPR for the service using that transport. Otherwise, it will ask the listener manager to start the listener and then ask the EPR for the service.
So, if someone passes a configuration context with a listener manager when creating a service client, the service client has access to listeners in the system through the corresponding listener manager. As a result, if someone invokes a two-channel invocation, the service client can use the running transport listeners as its client-side listener for the response processing. To facilitate this, the listener manger has a static field to keep the configuration context. If you set that field at the time the listener manager is created, clients running inside the listener manager have the capability of using the server's configuration context. It should be noted that AxisServlet sets the static values; therefore, any client running inside Aixs2 war distribution can use AxisServlet itself as its transport receiver (no need to start a new listener for client response processing).
To access the server's configuration context, you can use the following line of code to create ServicClient:
ServiceClient serviceClient = new ServiceClient(ListenerManager.defaultConfigurationContext, null)
Axis2 default transport support
Axis2 comes with a set of default transports senders and receivers; most of them use standard libraries. It is obvious that more than 90% of the Web service utilization is based on HTTP transports, but there is more of a trend of using other transports as well, especially SMTP. As a result of SOAP theoretically being the underline communication mechanism, you can use any of the transport mechanisms to communicate between two SOAP nodes. Axis2 supports the following types of transports and it has senders and receivers for them as well.
As mentioned earlier, Axis2 is transport independent and it does not care about the type of the senders and receivers, or all the transport-related code written using interfaces. It is very easy to implement those interfaces and extend the transport framework. Therefore, adding and removing a transport sender/receiver is not a headache; implementing a transport for a given protocol is just a matter of implementing the sender and receiver and register them in axis2.xml. At last, the Listener Manager API is very useful for applications such as BEPL, WS-Eventing, and WS-Notification, and so on.