Satish Burnwal's List: WebServices

• Before I discuss SOAP encoding style's impact on performance, you should understand the differences between the three styles. SOAP RPC is the encoding style that offers you the most simplicity. You make a call to a remote object, passing along any necessary parameters. The SOAP stack serializes the parameters into XML, moves the data to the destination using transports such as HTTP and SMTP, receives the response, deserializes the response back into objects, and returns the results to the calling method. Whew! SOAP RPC handles all the encoding and decoding, even for very complex data types, and binds to the remote object automatically.

    

  Now, imagine that you have some data already in XML format. SOAP RPC also allows literal encoding of the XML data as a single field that is serialized and sent to the Web service host. This is what's referred to as RPC-literal encoding. Since there is only one parameter -- the XML tree -- the SOAP stack only needs to serialize one value. The SOAP stack still deals with the transport issues to get the request to the remote object. The stack binds the request to the remote object and handles the response.

    

  Lastly, in a SOAP document-style call, the SOAP stack sends an entire XML document to a server without even requiring a return value. The message can contain any sort of XML data that is appropriate to the remote service. In SOAP document-style encoding, the developer handles everything, including determining the transport (e.g., HTTP, MQ, SMTP), marshaling and unmarshaling the body of the SOAP envelope, and parsing the XML in the request and response to find the needed data.

• Note that by default, the Axis server is configured to only accept administration requests from the machine on which it resides - if you wish to enable remote administration, you must set the "enableRemoteAdmin" property of the AdminService to true. To do this, find the "server-config.wsdd" file in your webapp's WEB-INF directory. In it, you'll see a deployment for the AdminService. Add an option as follows:
• There are four "styles" of service in Axis. RPC services use the SOAP RPC conventions, and also the SOAP "section 5" encoding. Document services do not use any encoding (so in particular, you won't see multiref object serialization or SOAP-style arrays on the wire) but DO still do XML<->Java databinding.
• Let's take a look at how this works in practice. Go look at samples/userguide/example5/BeanService.java. The key thing to notice is that the argument to the service method is an Order object. Since Order is not a basic type which Axis understands by default, trying to run this service without a type mapping will result in a fault.
• One, serializer, is the Java class name of the Serializer factory which gets the serializer to be used to marshal an object of the specified Java class (i.e., my.java.thingy) into XML. Another, deserializer, is the class name of a Deserializer factory that gets the deserializer to be used to unmarshall XML into the correct Java class.
• We provide a "WSDL2Java" tool which will build Java proxies and skeletons for services with WSDL descriptions.
• When you make a service available using Axis, there is typically a unique URL associated with that service. For JWS files, that URL is simply the path to the JWS file itself. For non-JWS services, this is usually the URL "http://<host>/axis/services/<service-name>".
• The generated files will reside in the directory "AddressFetcher2". They are put here because that is the target namespace from the WSDL and namespaces map to Java packages.
• To support this kind of mapping, and also to enable the serialization/deserialization of XML attributes, we have a type metadata system which allows us to associate Java data classes with descriptors which control these things.

• A note about the name of the SDI. The name of the SDI is typically the name of the portType. However, to construct the SDI, WSDL2Java needs information from both the portType and the binding. (This is unfortunate and is a topic of discussion for WSDL version 2.)

     
• Why? We could have one portType - pt - and two bindings - bRPC and bDoc. Since document/literal changes what the interface looks like, we cannot use a single interface for both of these bindings, so we end up with two interfaces - one named pt and another named bDoc - and two stubs - bRPCStub (which implements pt) and bDocStub (which implements bDoc).
• A Stub class implements the SDI. Its name is the binding name with the suffix "Stub". It contains the code which turns the method invocations into SOAP calls using the Axis Service and Call objects. It stands in as a proxy (another term for the same idea) for the remote service
• Normally, a client program would not instantiate a stub directly. It would instead instantiate a service locator and call a get method which returns a stub. This locator is derived from the service clause in the WSDL. WSDL2Java generates two objects from a service clause.
• The service interface defines a get method for each port listed in the service element of the WSDL. The locator is the implementation of this service interface.
• public class Tester {  public static void main(String [] args) throws Exception {  // Make a service  AddressBookService service = new AddressBookServiceLocator();   // Now use the service to get a stub which implements the SDI.  AddressBook port = service.getAddressBook();   // Make the actual call  Address address = new Address(...);  port.addEntry("Russell Butek", address);  } }
• public static void main(String [] args) throws Exception {  // Make a service  AddressBookService service = new AddressBookServiceLocator();   // Now use the service to get a stub which implements the SDI.  AddressBook port = service.getAddressBook();   // Make the actual call  Address address = new Address(...);  port.addEntry("Russell Butek", address);  }
• Just as a stub is the client side of a Web Service represented in Java, a skeleton is a Java framework for the server side. To make skeleton classes, you just specify the "--server-side --skeletonDeploy true" options to WSDL2Java.
• java org.apache.axis.wsdl.WSDL2Java --server-side AddressBook.wsdl
• The skeleton class is the class that sits between the Axis engine and the actual service implementation
• this.impl = new AddressBookSOAPBindingImpl();
• WSDL2Java also generates an implementation template from the binding:
• This template could actually be used as a test implementation but, as you can see, it doesn't do anything. It is intended that the service writer fill out the implementation from this template.

• The answer to most "where do I find..." questions for an Axis web service is "in the MessageContext." Essentially everything Axis knows about a given request/response can be retrieved via the MessageContext. Here Axis stores:

     
     
  • A reference to the AxisEngine
     
  • The request and response messages (org.apache.axis.Message objects available via getter and setter methods)
     
  • Information about statefulness and service scope (whether the service is maintaining session information, etc.)
     
  • The current status of processing (whether or not the "pivot" has been passed, which determines whether the request or response is the current message)
     
  • Authentication information (username and password, which can be provided by a servlet container or other means)

20 more annotations...