xdocs/migration.html - axis-axis2-java-core - Git at Google

 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
 <html>
 <head>
   <meta http-equiv="content-type" content="">
   <title>Migrating from Axis 1.x</title>
 </head>

 <body lang="en">
 <h1>Migrating from Axis 1.x to Axis 2</h1>

 <h2>Compatibility</h2>

 <p>Axis1.x and Axis2 have been evolved from different architectures.</p>

 <p>Speed - Axis2 is based on StAX API, which gives greater speed than SAX
 event base parsing that has been used in Axis1.x.</p>

 <p>Stability - Axis2 has fixed phases and for extensions an area of user
 defined phases. This allows far more stability and flexibility than
 Axis1.x.</p>

 <p>Transport framework - Simple abstraction designing of transports (i.e.,
 senders and listeners for SOAP over various protocols such as SMTP, etc),
 allow far more flexibility and the core of the engine is completely
 transport-independent.</p>

 <p>WSDL Support - Axis2 supports version 1.1 and 2.0, which allow creating
 stubs and skeletons, to manipulate web service arena.</p>

 <p>Component - Oriented Architecture - This is merely through archives (.mar
 and .aar) . Easily reusable components such as Handlers, Modules allow
 patterns processing for your applications, or to distribute to partners.
 Axis2 more concern on the "Module" concept rather Handler concept. Modules
 contain handlers that have been ordered through phase rules. which being
 ordered to specific service(s).</p>

 <h2>Getting Started</h2>

 <p>Lets look at a simple example of echoing at client API</p>

 <p><b>Axis 1.x</b></p>
 <pre>import ..
 public class TestClient {
         public static void main(String [] args) {
                 try {
                         String endpoint = ...
                         Service service = new Service();
                         Call call = (Call) service.createCall();
                         call.setTargetEndpointAddress( new java.net.URL(endpoint) );
                         call.setOperationName(new QName("http://soapinterop.org/", echoString"));
                         String ret = (String) call.invoke( new Object[] { "Hello!" } );
                         System.out.println("Sent 'Hello!', got '" + ret + "'");
                 } catch (Exception e) {
                         System.err.println(e.toString());
                 }
         }
 }</pre>

 <p><b>Axis 2</b></p>
 <pre>import ....
 public class EchoBlockingClient {
         private static EndpointReference targetEPR = new EndpointReference(
         AddressingConstants.WSA_TO,
                                 "http://127.0.0.1:8080/axis2/services/MyService/echo");
         public static void main(String[] args) {
                 try {
                         OMElement payload = ClientUtil.getEchoOMElement();
                         Call call = new Call();
                         call.setTo(targetEPR);
                         call.setTransportInfo(Constants.TRANSPORT_HTTP,Constants.TRANSPORT_HTTP,false);
                         //Blocking invocation
                         OMElement result = (OMElement) call.invokeBlocking("echo",payload);
                         ...
                 } catch (AxisFault axisFault) {
                         axisFault.printStackTrace();
                 } catch (XMLStreamException e) {
                         e.printStackTrace();
                 }
         }
 }</pre>

 <p>It has clearly depicted that the invocation in Axis2 is dealt with SOAP
 body element itself. Here the invocation is synchronous, and Axis2 can handle
 Asynchronous invocation as well. Above "payload" is the SOAP body element
 which should go in the Envelop.</p>

 <p>Once the service is called through Stub in Axis2, "payload" is according
 to the data binding framework that will be using. So the extra work of
 "payload" will be vanished.</p>

 <p>Apart from Synchronous invocation, Axis2 support Asynchronous invocation
 through invokeNonBlocking(). Synchronous/Asynchronous invocations can handle
 both single/double HTTP connection.</p>

 <p>With the advance architecture Axis2 is capable of handling Megabytes of
 Requests and Responses, which is far form Axis1.x.</p>

 <h2>Custom Deployment of Services, Handlers and Modules</h2>

 <p>In Axis 1.x deployment of services is via WSDD, which is for my opinion
 highly cumbersome. Service deployment in Axis2 is straight forward and
 dynamic. Dynamic behavior is from the Administrator facility given by
 development in server side. It's just a matter of creating a .aar file, and
 deploying it ,which more detail is given in the Axis2 user guide.</p>

 <p>Axis2 is far way from Handler concept and more into the Module concept,
 which is abstractly speaking, a collection of handlers with Rules of
 governing. Modules created as a .mar file. It has module.xml, which is the
 brain behind manipulating handlers.</p>

 <p>When a service is called through a handler, it is just a matter of giving
 reference to the module that includes the handler in the service.xml. Apart
 from that a handler can be directly called to a particular service, via
 service.xml, no module is needed, and several handlers can be invoked when
 the handlers are registered with the proper phases.</p>

 <p>Services are hot deployable in Axis2 and dynamic, but Modules. This is one
 feature, which is unique to Axis2.</p>

 <h2>Transports for HTTP Connection</h2>

 <p>Axis2 comes with two  CommonsHTTPTransportSender which is based on
 commons-httpclient. The configuration of the transport is as follows,</p>
 <pre>call.setTransportInfo(Constants.TRANSPORT_HTTP, Constants.TRANSPORT_HTTP, false);</pre>

 <p>It should be noted that axis2.xml should be configured to call the commons
 transports, with the statement,</p>
 <pre>...&lt;transportSender name="commons-http" class="org.apache.axis2.transport.http.CommonsHTTPTransportSender"&gt; &lt;parameter name="PROTOCOL" locked="xsd:false"&gt;HTTP/1.1&lt;/parameter&gt; &lt;parameter name="Transfer-Encoding" locked="xsd:false"&gt;chunked&lt;/parameter&gt;&lt;/transportSender&gt;...</pre>

 <p>In above snippet it should be noted that transport is configured to handle
 the chunked stream as well. Some web services, such as .NET web service
 invocations are done through this transport, as it handle all possible HTTP
 request and responses.</p>

 <p>Data Binding Support</p>

 <p>Xml-beans is used to provide data binding support. In Axis2, xml is
 manipulated via AXIOM, which is based on StAX API. XML give full schema
 support. Thus, serialization and de-serialization of Xml is handle in Axis2
 via xml-data binding framework.</p>

 <h2>Best Usage</h2>

 <p>Axis1.x and Axis2 have different ways of seen the SOAP stack. So the best
 way to migrate can be done through following the User guide and Architecture
 guide properly in Axis2. Axis2 is straight forward and friendly.</p>
 </body>
 </html>
	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
	<html>
	<head>
	<meta http-equiv="content-type" content="">
	<title>Migrating from Axis 1.x</title>
	</head>

	<body lang="en">
	<h1>Migrating from Axis 1.x to Axis 2</h1>

	<h2>Compatibility</h2>

	<p>Axis1.x and Axis2 have been evolved from different architectures.</p>

	<p>Speed - Axis2 is based on StAX API, which gives greater speed than SAX
	event base parsing that has been used in Axis1.x.</p>

	<p>Stability - Axis2 has fixed phases and for extensions an area of user
	defined phases. This allows far more stability and flexibility than
	Axis1.x.</p>

	<p>Transport framework - Simple abstraction designing of transports (i.e.,
	senders and listeners for SOAP over various protocols such as SMTP, etc),
	allow far more flexibility and the core of the engine is completely
	transport-independent.</p>

	<p>WSDL Support - Axis2 supports version 1.1 and 2.0, which allow creating
	stubs and skeletons, to manipulate web service arena.</p>

	<p>Component - Oriented Architecture - This is merely through archives (.mar
	and .aar) . Easily reusable components such as Handlers, Modules allow
	patterns processing for your applications, or to distribute to partners.
	Axis2 more concern on the "Module" concept rather Handler concept. Modules
	contain handlers that have been ordered through phase rules. which being
	ordered to specific service(s).</p>

	<h2>Getting Started</h2>

	<p>Lets look at a simple example of echoing at client API</p>

	<p><b>Axis 1.x</b></p>
	<pre>import ..
	public class TestClient {
	public static void main(String [] args) {
	try {
	String endpoint = ...
	Service service = new Service();
	Call call = (Call) service.createCall();
	call.setTargetEndpointAddress( new java.net.URL(endpoint) );
	call.setOperationName(new QName("http://soapinterop.org/", echoString"));
	String ret = (String) call.invoke( new Object[] { "Hello!" } );
	System.out.println("Sent 'Hello!', got '" + ret + "'");
	} catch (Exception e) {
	System.err.println(e.toString());
	}
	}
	}</pre>

	<p><b>Axis 2</b></p>
	<pre>import ....
	public class EchoBlockingClient {
	private static EndpointReference targetEPR = new EndpointReference(
	AddressingConstants.WSA_TO,
	"http://127.0.0.1:8080/axis2/services/MyService/echo");
	public static void main(String[] args) {
	try {
	OMElement payload = ClientUtil.getEchoOMElement();
	Call call = new Call();
	call.setTo(targetEPR);
	call.setTransportInfo(Constants.TRANSPORT_HTTP,Constants.TRANSPORT_HTTP,false);
	//Blocking invocation
	OMElement result = (OMElement) call.invokeBlocking("echo",payload);
	...
	} catch (AxisFault axisFault) {
	axisFault.printStackTrace();
	} catch (XMLStreamException e) {
	e.printStackTrace();
	}
	}
	}</pre>

	<p>It has clearly depicted that the invocation in Axis2 is dealt with SOAP
	body element itself. Here the invocation is synchronous, and Axis2 can handle
	Asynchronous invocation as well. Above "payload" is the SOAP body element
	which should go in the Envelop.</p>

	<p>Once the service is called through Stub in Axis2, "payload" is according
	to the data binding framework that will be using. So the extra work of
	"payload" will be vanished.</p>

	<p>Apart from Synchronous invocation, Axis2 support Asynchronous invocation
	through invokeNonBlocking(). Synchronous/Asynchronous invocations can handle
	both single/double HTTP connection.</p>

	<p>With the advance architecture Axis2 is capable of handling Megabytes of
	Requests and Responses, which is far form Axis1.x.</p>

	<h2>Custom Deployment of Services, Handlers and Modules</h2>

	<p>In Axis 1.x deployment of services is via WSDD, which is for my opinion
	highly cumbersome. Service deployment in Axis2 is straight forward and
	dynamic. Dynamic behavior is from the Administrator facility given by
	development in server side. It's just a matter of creating a .aar file, and
	deploying it ,which more detail is given in the Axis2 user guide.</p>

	<p>Axis2 is far way from Handler concept and more into the Module concept,
	which is abstractly speaking, a collection of handlers with Rules of
	governing. Modules created as a .mar file. It has module.xml, which is the
	brain behind manipulating handlers.</p>

	<p>When a service is called through a handler, it is just a matter of giving
	reference to the module that includes the handler in the service.xml. Apart
	from that a handler can be directly called to a particular service, via
	service.xml, no module is needed, and several handlers can be invoked when
	the handlers are registered with the proper phases.</p>

	<p>Services are hot deployable in Axis2 and dynamic, but Modules. This is one
	feature, which is unique to Axis2.</p>

	<h2>Transports for HTTP Connection</h2>

	<p>Axis2 comes with two CommonsHTTPTransportSender which is based on
	commons-httpclient. The configuration of the transport is as follows,</p>
	<pre>call.setTransportInfo(Constants.TRANSPORT_HTTP, Constants.TRANSPORT_HTTP, false);</pre>

	<p>It should be noted that axis2.xml should be configured to call the commons
	transports, with the statement,</p>
	<pre>...<transportSender name="commons-http" class="org.apache.axis2.transport.http.CommonsHTTPTransportSender"> <parameter name="PROTOCOL" locked="xsd:false">HTTP/1.1</parameter> <parameter name="Transfer-Encoding" locked="xsd:false">chunked</parameter></transportSender>...</pre>

	<p>In above snippet it should be noted that transport is configured to handle
	the chunked stream as well. Some web services, such as .NET web service
	invocations are done through this transport, as it handle all possible HTTP
	request and responses.</p>

	<p>Data Binding Support</p>

	<p>Xml-beans is used to provide data binding support. In Axis2, xml is
	manipulated via AXIOM, which is based on StAX API. XML give full schema
	support. Thus, serialization and de-serialization of Xml is handle in Axis2
	via xml-data binding framework.</p>

	<h2>Best Usage</h2>

	<p>Axis1.x and Axis2 have different ways of seen the SOAP stack. So the best
	way to migrate can be done through following the User guide and Architecture
	guide properly in Axis2. Axis2 is straight forward and friendly.</p>
	</body>
	</html>