CPE 3010 Lecture 5 Java and Web Services

CPE 3010 Lecture 5 Java and Web Services 1

Java and Web Services Many Java gurus/ developers HATE XML and Web services. - too slow, too high an overhead, and “back to the future” because RPC is used and real objects can not be passed. Also no leasing in UDDI (yet). BUT, Web Services are THE ONLY GAME IN TOWN, TOWN so Sun offers Java frameworks/ APIs for dealing with Web Services - Java APIs for XML Processing and Web Services: JAXB, JAX- RPC - J 2 EE 1. 4 provides support for web services through the JAX-RPC 1. 1 API. It also supports JSR 109, that builds on JAX-RPC. 2

Java APIs for XML Processing & Web Services Document-oriented Java API for XML Processing (JAXP) -- processes XML documents using various parsers Java Architecture for XML Binding (JAXB) -- processes XML documents using schema-derived Java. Beans component classes SOAP with Attachments API for Java (SAAJ) -- sends SOAP messages over the Internet in a standard way Procedure-oriented Java API for XML-based RPC (JAX-RPC) -- sends SOAP method calls to remote parties over the Internet and receives the results Java API for XML Registries (JAXR) -- provides a standard way to access business registries and share information 3

Using Java and Web Services 4

Present and Future Java APIs 5

Java APIs • Not used extensively: • Java API for XML Processing (JAXP) parsing and processing XML documents and a transformation engine supporting XSLT; • Java API for XML Registries (JAXR) defines Java APIs for accessing XML registries. It will support both eb. XML registries and repositories and UDDI; • Java API for XML Messaging (JAXM) provides Java support for sending and receiving SOAP messages; · Used extensively: · Java Architecture for XML Binding (JAXB) makes it easy to map XML data into Java objects; · Java API for Remote Procedure Call (JAX-RPC), a procedure call is transmitted as XML. 6

JAXP - parses data as a stream of events or builds an object representation of it. - supports XSLT (XML Stylesheet Language Transformations), providing control over the presentation of the data and enabling you to convert the data to other XML documents or to other formats, such as HTML. - provides namespace support. - allows you to use any XML-compliant parser from within your application - also allows you to plug in an XSL processor, to control how your XML data is displayed. 7

Example Using JAXP http: //java. sun. com/developer/technical. Articles/xml/brazil/ index. html 8

SAX API – Simple XML Parsing Event-based parser that reads an XML document from beginning to end. Each time it recognizes a syntax construction, it notifies the application that is running it by calling methods from the Content. Handler interface. For example, when the parser comes to a less than symbol ("<"), it calls the start. Element method; when it comes to character data, it calls the characters method; when it comes to the less than symbol followed by a slash ("</"), it calls the end. Element method, and so on. 9

Running XML Example <price. List> <coffee> <name>Mocha Java</name> <price>11. 95</price> </coffee> <name>Sumatra</name> <price>12. 50</price> </coffee> </price. List> 10

SAX Example <price. List> [parser calls start. Element] <coffee> [parser calls start. Element] <name>Mocha Java</name> [parser calls start. Element, characters, and end. Element] <price>11. 95</price> [parser calls start. Element, characters, and end. Element] </coffee> [parser calls end. Element] 11

SAX, cont’d. You need to write a subclass implementing the appropriate methods to get the functionality you want. To get the price per pound for Mocha Java, write a class extending Default. Handler (the default implementation of Content. Handler) to implement the methods start. Element and characters. Create a SAXParser object from a SAXParser. Factory object. You would call the method parse on it, passing it the price list and an instance of your new handler class (with its new implementations of the methods start. Element and characters). In this example, price list is a file, but parse can also take other input sources, an Input. Stream object, a URL, or an Input. Source object. SAXParser. Factory factory = SAXParser. Factory. new. Instance(); SAXParser sax. Parser = factory. new. SAXParser(); sax. Parser. parse("price. List. xml", handler); 12

SAX, cont’d. The result of calling the method parse depends on how the methods in handler were implemented. The SAX parser will go through the file price. List. xml line by line, calling the appropriate methods. In addition to the methods already mentioned, the parser will call other methods such as start. Document, end. Document, ignorable. White. Space, and processing. Instructions, but these methods have default implementations and do nothing. 13

SAX, cont’d. The following implements the methods characters and start. Element so that they find the price for Mocha Java and print it out. These methods work together to look for the name element, the characters "Mocha Java", and the price element immediately following Mocha Java. These methods use three flags to keep track of which conditions have been met. 14

SAX Example, cont’d. public void start. Element(. . . , String element. Name, . . . ) { if(element. Name. equals("name")){ in. Name = true; } else if(element. Name. equals("price") && in. Mocha. Java ) { in. Price = true; in. Name = false; } } public void characters(char [] buf, int offset, int len) { String s = new String(buf, offset, len); if (in. Name && s. equals("Mocha Java")) { in. Mocha. Java = true; in. Name = false; } else if (in. Price) { System. out. println("The price of Mocha Java is: " + s); in. Mocha. Java = false; in. Price = false; } } } 15

SAX, cont’d. Once the parser has come to the Mocha Java coffee element, here is the relevant state after the following method calls: next invocation of start. Element -- in. Name is true next invocation of characters -- in. Mocha. Java is true next invocation of start. Element -- in. Price is true next invocation of characters -- prints price 16

SAX, cont’d. SAX parser can perform validation while parsing, to check that the data follows the rules specified in the XML document's schema. A SAX parser will validate if it is created by a SAXParser. Factory that has validation turned on. This is done for the SAXParser. Factory object factory in the following line of code. factory. set. Validating(true); The parser knows which schema to use for validation by an XML document. The schema for the price list is price. List. DTD, so the DOCTYPE declaration should be similar to this: <!DOCTYPE Price. List SYSTEM "price. List. DTD"> 17

Object Model Parsing Document Object Model (DOM), defined by W 3 C, is a set of interfaces for building an object representation, in the form of a tree, of a parsed XML document. Once you build the DOM, you manipulate it with DOM methods such as insert and remove, as other tree data structures. Unlike SAX, a DOM parser allows random access to pieces of data in an XML document. With a SAX parser, you can only read an XML document, but with a DOM parser, you can build an object representation and manipulate it in memory, adding a new element or deleting one. 18

DOM, cont’d. In the previous example, SAX looked for one piece of data in a document. Using a DOM parser would have required having the whole document object model in memory, which is generally less efficient for searches involving just a few items, if the document is large. The next example adds a new coffee to the price list using a DOM parser. We cannot use a SAX parser for modifying the price list because it only reads data. Add Kona coffee to the price list. Read the XML price list file into a DOM and tinsert the new coffee element, with its name and price. The following code fragment creates a Document. Builder. Factory object, which is then used to create the Document. Builder object builder. The code then calls the parse method on builder, passing it the file price. List. xml. 19

DOM Example Document. Builder. Factory factory = Document. Builder. Factory. new. Instance(); Document. Builder builder = factory. new. Document. Builder(); Document document = builder. parse("price. List. xml"); 20

DOM Example, cont’d. document is DOM representation of the price list. The following code adds a new coffee (with the name "Kona" and a price of "13. 50") to the price list. Because we want to add the new coffee right before the coffee whose name is "Mocha Java", first get a list of the coffee elements and iterate through the list to find "Mocha Java". Using the Node interface in org. w 3 c. dom, the code creates a Node object for the new coffee element and the name and price elements. The name and price elements contain character data, so the code creates a Text object for each of them and appends the text nodes to the nodes representing the name and price elements. 21

DOM Example, cont’d. Node root. Node = document. get. Document. Element(); Node. List list = document. get. Elements. By. Tag. Name("coffee"); // Loop through the list. for (int i=0; i < list. get. Length(); i++) { this. Coffee. Node = list. item(i); Node this. Name. Node = this. Coffee. Node. get. First. Child(); if (this. Name. Node == null) continue; if (this. Name. Node. get. First. Child() == null) continue; if (! this. Name. Node. get. First. Child() instanceof org. w 3 c. dom. Text) continue; String data = this. Name. Node. get. First. Child(). get. Node. Value(); if (! data. equals("Mocha Java")) continue; 22

DOM Example, cont’d. //We're at the Mocha Java node. Create and insert the new element. Node new. Coffee. Node = document. create. Element("coffee"); Node new. Name. Node = document. create. Element("name"); Text tn. Node= document. create. Text. Node("Kona"); new. Name. Node. append. Child(tn. Node); Node new. Price. Node = document. create. Element("price"); Text tp. Node = document. create. Text. Node("13. 50"); new. Price. Node. append. Child(tp. Node); new. Coffee. Node. append. Child(new. Name. Node); new. Coffee. Node. append. Child(new. Price. Node); root. Node. insert. Before(new. Coffee. Node, this. Coffee. Node); break; } 23

DOM Output to XML To transform the DOM tree to an XML document, the following code first creates a Transformer object that will perform the transformation. Transformer. Factory trans. Factory = Transformer. Factory. new. Instance(); Transformer transformer = trans. Factory. new. Transformer(); Using the DOM tree root node, the following code constructs a DOMSource object as the source of the transformation. DOMSource source = new DOMSource(document); 24

DOM Output, cont’d. The following code creates a Stream. Result object to take the results of the transformation and transforms the tree into an XML file. File new. XML = new File("new. XML. xml"); File. Output. Stream os = new File. Output. Stream(new. XML); Stream. Result result = new Stream. Result(os); transformer. transform(source, result); 25

JAXB compiles an XML schema into one or more classes. The generated classes handle all the details of XML parsing and formatting, they ensure that the constraints expressed in the schema are enforced, and in many cases they are much more efficient than using SAX or DOM. 26

JAXB Binding 27

JAXB, cont’d. JAXB generates Java classes from XML schemas. JAXB provides methods for unmarshalling an XML instance document into a content tree of Java objects, and then marshalling the content tree back into an XML document. JAXB hides the details and gets rid of the extra steps in SAX and DOM-- JAXB classes describe only the relationships defined in the schemas. 28

JAXB Architecture 29

JAXB Summary Generate and compile JAXB classes from a source schema, and build an application that implements these classes Run the application to unmarshal, process, validate, and marshal XML content through the JAXB binding framework 30

JAXB Steps Generate classes. An XML schema is used as input to the JAXB binding compiler to generate JAXB classes based on that schema. Compile classes. All of the generated classes, source files, and application code must be compiled. Unmarshal. XML documents written according to the constraints in the source schema are unmarshalled. Generate content tree. The unmarshalling process generates a content tree of data objects instantiated from the generated JAXB classes; this content tree represents the structure and content of the source XML documents. Validate (optional). Validation of the source before generating the content tree. Process content. The client application can modify the XML data represented by the Java content tree by means of interfaces generated by the binding compiler. Marshal. The processed content tree is marshalled out to one or more XML output documents. The content may be validated before marshalling. 31

JAXB Details javax. xml. bind defines abstract classes and interfaces used directly with content classes. javax. xml. bind defines the Unmarshaller, Validator, and Marshaller classes. JAXBContext is the entry point to JAXB. A JAXBContext instance manages the binding relationship between XML element names to Java content interfaces for a JAXB implementation to be used by the unmarshal, marshal and validation operations. javax. xml. bind also defines validation event and exception classes. javax. xml. bind. util contains utility classes to manage marshalling, unmarshalling, and validation events. javax. xml. bind. helper provides partial default implementations for some of the javax. xml. bind interfaces. Implementations of JAXB can extend these classes and implement the abstract methods. These APIs are not intended to be directly used by applications using JAXB architecture. 32

JAXB Details The JAXBContext class provides an abstraction for managing the information necessary for unmarshal, marshal and validate. JAXBContext jc = JAXBContext. new. Instance( "com. acme. foo: com. acme. bar" ); The context. Path parameter contains a list of packages that contain schema-derived interfaces-- the interfaces generated by the JAXB binding compiler. This parameter initializes the JAXBContext object to enable management of the schema-derived interfaces. The JAXB provider implementation must supply an implementation class containing a method with the following signature: public static JAXBContext create. Context( String context. Path, Class. Loader class. Loader ) throws JAXBException; 33

Unmarshalling The Unmarshaller class in the javax. xml. bind package converts XML data into a tree of Java objects. The unmarshal method for a schema allows for any global XML element declared in the schema to be unmarshalled as the root of an instance document. The JAXBContext object allows the merging of global elements across a set of schemas (listed in the context. Path). Since each schema can belong to distinct namespaces, the unification of schemas to an unmarshalling context should be namespaceindependent. A client application can unmarshal XML documents that are instances of any of the schemas listed in the context. Path: 34

Unmarshalling, cont’d. JAXBContext jc = JAXBContext. new. Instance( "com. acme. foo: com. acme. bar" ); Unmarshaller u = jc. create. Unmarshaller(); Foo. Object foo. Obj = (Foo. Object)u. unmarshal( new File( "foo. xml" ) ); // ok Bar. Object bar. Obj = (Bar. Object)u. unmarshal( new File( "bar. xml" ) ); // ok Baz. Object baz. Obj = (Baz. Object)u. unmarshal( new File( "baz. xml" ) ); // error, "com. acme. baz" not in context. Path 35

Marshalling The Marshaller class converts a Java content tree back into XML data. A simple example that unmarshals an XML document and then marshals it back out is a follows: 36

Marshalling, cont’d. JAXBContext jc = JAXBContext. new. Instance( "com. acme. foo" ); // unmarshal from foo. xml Unmarshaller u = jc. create. Unmarshaller(); Foo. Object foo. Obj = (Foo. Object)u. unmarshal( new File( "foo. xml" ) ); // marshal to System. out Marshaller m = jc. create. Marshaller(); m. marshal( foo. Obj, System. out ); 37

JAXB Examples http: //java. sun. com/webservices/docs/1. 4/tutorial/doc/inde x. html 38

JAXB Customisation Reasons for modifying default bindings: Create API documentation for the schema-derived JAXB classes, etc. ; add Javadoc annotations. Provide meaningful names : To resolve name collisions. To provide names for typesafe enumeration constants. To provide better names for the Java representation of unnamed model groups when they are bound to a Java property or class. To provide more meaningful package names. Overriding default bindings; for example: Specify that a model group should be bound to a class rather than a list. Specify that a fixed attribute can be bound to a Java constant. Override the specified default binding of XML Schema built-in datatypes to Java datatypes. 39

JAX-RPC builds Web services and clients that use remote procedure calls and XML. In JAX-RPC, a remote procedure call is represented by an XMLbased protocol such as SOAP. Although SOAP messages are complex, the JAX-RPC API hides this complexity from the application developer. On the server side, the developer specifies the remote procedures by defining methods in a Java interface. The developer also codes one or more classes that implement those methods. A client creates a proxy, a local object representing the service, and then invokes methods on the proxy. With JAX-RPC, the developer does not generate or parse SOAP messages. It is the JAX-RPC runtime system that converts the API calls and responses to and from SOAP messages. 40

JAX-RPC In JAX-RPC, a remote procedure call is represented by an XML-based protocol such as SOAP. The SOAP specification defines the envelope structure, encoding rules, and conventions for representing remote procedure calls and responses. These calls and responses are transmitted as SOAP messages (XML files) over HTTP. JAX-RPC API hides SOAP complexityfrom the application developer. On the server side, the developer specifies the remote procedures by defining methods in an interface. The developer also codes one or more classes that implement the methods. A client creates a proxy (a local object representing the service) and then simply invokes methods on the proxy. With JAX-RPC, the developer does not generate or parse SOAP messages. JAX-RPC runtime converts the API calls and responses to and from SOAP messages. 41

JAX-RPC 42

Developing a JAX-RPC Web Service The starting point for developing a JAX-RPC Web service is the service endpoint interface. A service endpoint interface (SEI) is a Java interface that declares the methods that a client can invoke on the service. Use the SEI, the wscompile tool, and two configuration files to generate the WSDL specification of the Web service and the stubs that connect a Web service client to the JAX-RPC runtime. Together, wscompile, the deploytool utility, and the Application Server provide the Application Server’s implementation of JAX-RPC. 43

Summary of Steps These are the basic steps for creating the Web service and client: 1. Code the SEI and implementation class and interface configuration file. 2. Compile the SEI and implementation class. 3. Use wscompile to generate the files required to deploy the service. 4. Use deploytool to package the files into a WAR file. 5. Deploy the WAR file. The tie classes (which are used to communicate with clients) are generated by the Application Server during deployment. 6. Code the client class and WSDL configuration file. 7. Use wscompile to generate and compile the stub files. 8. Compile the client class. 9. Run the client. 44

JAX-RPC: Overview 45

JAX-RPC: Service Side Use Cases 46

JAX-RPC: Service Side Service endpoint definition starts with a Java service endpoint interface. Service developer can map a WSDL document to a Java service endpoint interface. Once JAX-RPC service endpoint is defined and implemented, deployment requires server-side JAX-RPC runtime. Deployment includes generation of artifacts (skeleton or tie class) based on the service endpoint interface. During deployment, the tool configures one or more protocol bindings for this service endpoint. A binding ties an abstract service endpoint definition to a specific protocol and transport. An example of a binding is SOAP over HTTP. 47

JAX-RPC: Service Side Runtime 48

JAX-RPC: Client Side Use Cases 49

JAX-RPC Client Side Client uses the WSDL document to import the service. A WSDL-to-Java mapping tool generates client side artifacts (includes stub class, service endpoint interface and additional classes) for the service and its ports. Note that a service client may use dynamic invocation interface (DII) or a dynamic proxy mechanism instead of a generated stub class to invoke a remote method on a service endpoint. 50

JAX-RPC: Client Side Runtime 51

Client invokes Service 52

Remote Method Call The processing of a remote method call includes : • Map remote method call to the SOAP message representation: map parameters, return value and exceptions (for the remote method call) to the corresponding SOAP message; serialization and deserialization based on the mapping between Java types and XML data types. • Process SOAP message: Process SOAP message based on the mapping of call to the SOAP representation. • Process HTTP request: Transmit SOAP request as part of HTTP request. SOAP response is transmitted as HTTP response. 53

Service Side Response 54

Create Service (Simplified) Service definition interface extends java. rmi. Remote and its methods throw a java. rmi. Remote. Exception object. package coffees; import java. rmi. Remote. Exception; public interface Coffee. Order. IF extends Remote { public Coffee [] get. Price. List() throws Remote. Exception; public String order. Coffee(String coffee. Name, int quantity) throws Remote. Exception; } The method get. Price. List returns an array of Coffee objects, each of which contains a name and a price. 55

Simple Service, cont’d. The method get. Price. List will query the company's database to get the current information and return the result as an array of Coffee objects. The second method, order. Coffee, will also need to query the database to see if the particular coffee specified is available in the quantity ordered. The implementation will set the internal order process in motion and send a reply informing the customer that the order will be filled. 56

Simple Service, cont’d. package coffees; public class Coffee. Order. Impl implements Coffee. Order. IF { public Coffee [] get. Price. List() throws Remote. Exception; {. . . } public String order. Coffee(String coffee. Name, int quantity) throws Remote. Exception; {. . . } } 57

Simple Service, cont’d. The mapping tool uses the interface and implementation to generate the stub and tie classes and to create the WSDL description for the service. Packaging a Web service definition is done via a Web application archive (WAR). A WAR file is a JAR file for Web applications, . For example, the Coffee. Order service could be packaged in the file jaxrpc-coffees. war. An XML file called a deployment descriptor must be with the WAR with information for deploying a service definition. One of the files referenced in a web. xml file is a configuration file that is automatically generated by the mapping tool. Deploying Coffee. Order example in a Tomcat container can be accomplished by copying the jaxrpc-coffees. war file to webapps directory. 58

Coding the Client This Web services client creates an instance of Coffee. Order. IF and uses it to call the method get. Price. List. Then it accesses the price and name fields of each Coffee object in the array returned by the method get. Price. List in order to print them out. The class Coffee. Order. Service. Impl is one of the classes generated by the mapping tool. It is a stub factory whose only method is get. Coffee. Order. IF. It creates instances of Coffee. Order. IF. The instances of Coffee. Order. IF that are created by Coffee. Order. Service. Impl are client side stubs that can be used to invoke methods defined in the interface Coffee. Order. IF. The method get. Price. List will block until it has a response and returned it. Because a WSDL document is being used, the JAX-RPC runtime will get the service endpoint from it. 59

The Client, cont’d. public class Coffee. Client { public static void main(String[] args) { try { Coffee. Order. IF coffee. Order = new Coffee. Order. Service. Impl(). get. Coffee. Order. IF(); Coffee [] price. List = coffee. Order. get. Price. List(): for (int i = 0; i < price. List. length; i++) { System. out. print(price. List[i]. get. Name() + " "); System. out. println(price. List[i]. get. Price()); } } catch (Exception ex) { ex. print. Stack. Trace(); } }} 60

Client talks to Service !!! The JAX-RPC runtime determines the endpoint for the Coffee. Order service (which is its URI) from its WSDL description. If a WSDL document had not been used, you would need to supply the service's URI as a command line argument. java coffees. Coffee. Client The RPC is a static method call. The RPC was determined at compile time. It is possible to call a remote method dynamically at run time with the Dynamic Invocation Interface (DII) or a dynamic proxy. 61

JAX-RPC Supported Types Primitive types: boolean byte double float int long short java. lang. Boolean java. lang. Byte java. lang. Double java. lang. Float java. lang. Integer java. lang. Long java. lang. Short java. lang. String java. math. Big. Decimal java. math. Big. Integer java. net. URI java. util. Calendar java. util. Date java. util. Collection Classes: List Array. List Linked. List Stack Vector Map Hashtable Properties Tree. Map Set Hash. Set Tree. Set 62

JAX-RPC Value Types A value type is a class whose state may be passed between a client and remote service as a parameter or return value. For example, in an application for a university library, a client might call a remote procedure with a value type parameter named Book, a class that contains the fields Title, Author, and Publisher. A value type must have a public default constructor, not implement the java. rmi. Remote interface, and its fields must be supported JAX-RPC types. The value type may contain public, private, or protected fields: A public field cannot be final or transient. A non-public field must have corresponding getter and setter methods. 63

JAX-RPC – More Detail 64

Creating a Service These are the basic steps for creating a service: Code the service endpoint interface and implementation class. Build, generate, and package the files required by the service. Deploy the WAR file that contains the service. 65

Coding the Service A service endpoint interface declares the methods that a remote client may invoke on the service. In this example, the interface declares a single method named say. Hello. A service endpoint interface must conform to a few rules: It extends the java. rmi. Remote interface. It must not have constant declarations, such as public final static. The methods must throw the java. rmi. Remote. Exception or one of its subclasses. Method parameters and return types must be supported JAX-RPC types. 66

Service Example In this example, the service endpoint interface is Hello. IF. java: package helloservice; import java. rmi. Remote. Exception; public interface Hello. IF extends Remote { public String say. Hello(String s) throws Remote. Exception; } 67

Service Example, cont’d. package helloservice; public class Hello. Impl implements Hello. IF { public String message ="Hello"; public String say. Hello(String s) { return message + s; } } 68

Building the Service asant build The build task command executes these asant subtasks: compile-service generate-wsdl The compile-service Task This asant task compiles Hello. IF. java and Hello. Impl. java, writing the class files to the build subdirectory. 69

Building the Service, cont’d. The generate-wsdl Task The generate-wsdl task runs wscompile, which creates the WSDL and mapping files. The WSDL file describes the Web service and is used to generate the client stubs. The mapping file contains information that correlates the mapping between the Java interfaces and the WSDL definition. The files created are My. Hello. Service. wsdl and mapping. xml. The generate-wsdl task runs wscompile with the following arguments: wscompile -define -mapping build/mapping. xml -d build -nd build -classpath build config-interface. xml 70

Building, cont’d. The -classpath flag instructs wscompile to read the SEI in the build directory, and the -define flag instructs wscompile to create WSDL and mapping files. The -mapping flag specifies the mapping file name. The -d and -nd flags tell the tool to write class and WSDL files to the build subdirectory. The wscompile tool reads an interface configuration file that specifies information about the SEI. In this example, the configuration file is named config-interface. xml and contains the following: <? xml version="1. 0" encoding="UTF-8"? > <configuration xmlns="http: //java. sun. com/xml/ns/jax-rpc/ri/config"> <service name="My. Hello. Service" target. Namespace="urn: Foo" type. Namespace="urn: Foo" package. Name="helloservice"> <interface name="helloservice. Hello. IF"/> </service> </configuration> 71

Building, cont’d. This configuration file tells wscompile to create a WSDL file named My. Hello. Service. wsdl with the following information: The service name is My. Hello. Service. The WSDL target and type namespace is urn: Foo. The choice for what to use for the namespaces is up to you. The role of the namespaces is similar to the use of Java package names--to distinguish names that might otherwise conflict. For example, a company can decide that all its Java code should be in the package com. wombat. *. Similarly, it can also decide to use the namespace http: //wombat. com. The SEI is helloservice. Hello. IF. The package. Name attribute instructs wscompile to put the service classes into the helloservice package. 72

Packaging and Deploying Service Package and deploy the service using either deploytool or asant. Packaging and Deploying the Service with deploytool Behind the scenes, a JAX-RPC Web service is implemented as a servlet. Because a servlet is a Web component, you run the New Web Component wizard of the deploytool utility to package the service. During this process the wizard performs the following tasks: Creates the Web application deployment descriptor Creates a WAR file Adds the deployment descriptor and service files to the WAR file 73

Deploytool WAR File dialog box Select the button labeled Create New Stand-Alone WAR Module. In the WAR Location field, click Browse and navigate to <INSTALL>/j 2 eetutorial 14/examples/jaxrpc/helloservice/. In the File Name field, enter My. Hello. Service. Click Create Module File. Click Edit Contents. In the tree under Available Files, locate the <INSTALL>/j 2 eetutorial 14/examples/jaxrpc/helloservice/ directory. Select the build subdirectory. Click Add. Click OK. 74 Click Next.

Deploytool, cont’d. Choose Component Type dialog box Select the Web Services Endpoint button. Click Next. Choose Service dialog box In the WSDL File combo box, select WEB-INF/wsdl/My. Hello. Service. wsdl. In the Mapping File combo box, select build/mapping. xml. Click Next. Component General Properties dialog box In the Service Endpoint Implementation combo box, select helloservice. Hello. Impl. Click Next. Web Service Endpoint dialog box In the Service Endpoint Interface combo box, select helloservice. Hello. IF. In the Namespace combo box, select urn: Foo. In the Local Part combo box, select Hello. IFPort. The deploytool utility will enter a default Endpoint Address URI Hello. Impl in this dialog. This endpoint address must be updated in the next section. Click Next. Click Finish. 75

Deploytool, cont’d. Specifying the Endpoint Address To access My. Hello. Service, the tutorial clients will specify this service endpoint address URI: http: //localhost: 8080/hello-jaxrpc/hello The /hello-jaxrpc string is the context root of the servlet that implements My. Hello. Service. The /hello string is the servlet alias. To specify the endpoint address, you set the context root and alias as follows: In deploytool, select My. Hello. Service in the tree. Select the General tab. In the Context Root field, enter /hello-jaxrpc. In the tree, select Hello. Impl. Select the Aliases tab. In the Component Aliases table, add /hello. In the Endpoint tab, select hello for the Endpoint Address in the Sunspecific Settings frame. Select File Save. 76

Deploytool, cont’d. Deploying the Service In deploytool, perform these steps: In the tree, select My. Hello. Service. Select Tools Deploy. You can view the WSDL file of the deployed service by requesting the URL http: //localhost: 8080/hellojaxrpc/hello? WSDL in a Web browser. Now you are ready to create a client that accesses this service. 77

Asant Packaging and Deploying the Service with asant To package and deploy the helloservice example, follow these steps: In a terminal window, go to <INSTALL>/j 2 eetutorial 14/examples/jaxrpc/helloservice/. Run asant create-war. Make sure the Application Server is started. Set your admin username and password in <INSTALL>/j 2 eetutorial 14/examples/common/build. properties. Run asant deploy-war. You can view the WSDL file of the deployed service by requesting the URL http: //localhost: 8080/hello-jaxrpc/hello? WSDL in a Web browser. Now you are ready to create a client that accesses this service. 78

Undeploying the Service At this point in the tutorial, do not undeploy the service. When you are finished with this example, you can undeploy the service by typing this command: asant undeploy 79

Coding the Client Before invoking the remote methods on the stub the client must: Create a Stub object: (Stub)(new My. Hello. Service_Impl(). get. Hello. IFPort()) The code in this method is implementation-specific because it relies on a My. Hello. Service_Impl object, which is not defined in the specifications. The My. Hello. Service_Impl class will be generated by wscompile in the following section. Set the endpoint address that the stub uses to access the service: stub. _set. Property (javax. xml. rpc. Stub. ENDPOINT_ADDRESS_PROPERTY, args[0]); At runtime, the endpoint address is passed to Hello. Client in args[0] as a command-line parameter, which ant gets from the endpoint. address property in the build. properties file. Cast stub to the service endpoint interface, Hello. IF: Hello. IF hello = (Hello. IF)stub; 80

Coding the Client, cont’d. package staticstub; import javax. xml. rpc. Stub; public class Hello. Client { private String endpoint. Address; public static void main(String[] args) { System. out. println("Endpoint address = " + args[0]); try { Stub stub = create. Proxy(); stub. _set. Property (javax. xml. rpc. Stub. ENDPOINT_ADDRESS_PROPERTY, args[0]); Hello. IF hello = (Hello. IF)stub; System. out. println(hello. say. Hello("Duke!")); } catch (Exception ex) { ex. print. Stack. Trace(); } } private static Stub create. Proxy() { // Note: My. Hello. Service_Impl is implementation-specific. return (Stub) (new My. Hello. Service_Impl(). get. Hello. IFPort()); }} 81

Building the Client asant build Steps required in build: generate-stubs compile-client package-client The generate-stubs task runs the wscompile tool as follows: wscompile -gen: client -d build -classpath build config-wsdl. xml wscompile reads the WSDL file that was installed when the service was deployed. The wscompile command generates files based on the information in the WSDL file and on the command-line flags. The -gen: client flag instructs wscompile to generate the stubs, serializers, and value types. The compile-client task compiles src/Hello. Client. java and writes the class file to the build subdirectory. The package-client task packages the files created by the generate 82 the dist/client. jar file. stubs and compile-client tasks into

Full JAX-RPC Examples http: //java. sun. com/j 2 ee/1. 4/docs/tutorial/doc/index. html JAX-RPC 83

XMS- Security XML and Web Services Security (XWS-Security) for message-level security. Security information is in the SOAP message; security information travels with the message. For example, a portion of the message may be signed by a sender and encrypted for a particular receiver. When the message is sent from the initial sender, it may pass through intermediate nodes before reaching its intended receiver. In this scenario, the encrypted portions can’t be read by any intermediate nodes and can only be decrypted by the intended receiver. message-level security is also sometimes referred to as end-to-end security. Features: Support for securing JAX-RPC applications. A framework for a JAX-RPC application developer to secure applications by signing/verifying parts of SOAP messages and/or encrypting/decrypting parts of a SOAP message. The message sender can also associate security tokens with the message. A token may hold the identity of the sender, a user 84 name and password.

SAAJ: Java API for SOAP with Attachments 85

SAAJ Extends DOM SAAJ APIs extend their counterparts in org. w 3 c. dom: The Node interface extends the org. w 3 c. dom. Node interface. The SOAPElement interface extends both the Node interface and the org. w 3 c. dom. Element interface. The SOAPPart class implements the org. w 3 c. dom. Document interface. The Text interface extends the org. w 3 c. dom. Text interface. The SOAPPart of a SOAPMessage is a DOM Level 2 Document, and can be manipulated by applications, tools and libraries that use DOM. 86

SOAP Connections SOAP messages are sent and received over a connection. The connection is represented by a SOAPConnection object, which goes from the sender directly to its destination. Messages sent using the SAAJ API are request-response messages. They are sent over a SOAPConnection object with the method call, which sends a message (a request) and then blocks until it receives the reply (a response). 87

SOAP SAAJ Details and Examples http: //java. sun. com/webservices/docs/1. 2/tutorial/doc/SAA J. html 88

JAXR enables Java software programmers to use a single API to access a variety of XML registries. A unified JAXR information model describes content and metadata within XML registries. Developers can write registry client programs that are portable across different target registries. The JAXR specification includes detailed bindings between the JAXR information model and both the eb. XML Registry and the UDDI version 2 specifications. 89

JAXR 90

JAXR Architecture A JAXR client: accesses a business registry via a JAXR provider. A JAXR provider : provides access to a specific registry provider or to a class of registry providers A JAXR provider implements two main packages: javax. xml. registry, which consists of the API interfaces and classes that define the registry access interface. javax. xml. registry. infomodel , which consists of interfaces that define the information model for JAXR. These interfaces define the types of objects that reside in a registry and how they relate to each other. The basic interface in this package is the Registry. Object interface. Its subinterfaces include Organization, Service, and Service. Binding. 91

JAXR Provider Interfaces in the javax. xml. registry package Connection. represents a client session with a registry provider. The client must create a connection with the JAXR provider. Registry. Service. The client obtains a Registry. Service object from its connection. The Registry. Service object in turn enables the client to obtain the interfaces it uses to access the registry. Business. Query. Manager, allows the client to search a registry for information by the javax. xml. registry. infomodel interfaces. Business. Life. Cycle. Manager, which allows the client to modify the information in a registry by either saving it (updating it) or deleting it. 92

JAXR Client Establishing a Connection Properties props = new Properties(); props. set. Property("javax. xml. registry. query. Manager. UR L", "http: //uddi. ibm. com/testregistry/inquiryapi"); props. set. Property("javax. xml. registry. life. Cycle. Manager URL", "https: //uddi. ibm. com/testregistry/publishapi"); The client then sets the properties for the connection factory and creates the connection: conn. Factory. set. Properties(props); Connection connection = conn. Factory. create. Connection(); 93

JAXR Client Querying a Registry - By name - By classification 94

Finding Services and Service. Bindings Iterator org. Iter = orgs. iterator(); while (org. Iter. has. Next()) { Organization org = (Organization) org. Iter. next(); Collection services = org. get. Services(); Iterator svc. Iter = services. iterator(); while (svc. Iter. has. Next()) { Service svc = (Service) svc. Iter. next(); Collection service. Bindings = svc. get. Service. Bindings(); Iterator sb. Iter = service. Bindings. iterator(); while (sb. Iter. has. Next()) { Service. Binding sb = (Service. Binding) sb. Iter. next(); } } 95

Full JAX-RPC, SAAJ and JAXR Example http: //java. sun. com/webservices/docs/1. 2/tutorial/doc/CB. html 96

Full Example, cont’d. 97

Full Example, cont’d. The Coffee Break server obtains coffee from distributors. Server uses SAAJ to communicate with one distributor. It uses JAXR to send a query searching for coffee distributors. The Coffee Break server requests price lists from each of the coffee distributors. The server makes RPCs and waits for response, a Java. Beans component representing a price list. The SAAJ distributor returns price lists as XML documents. Server processes the price lists from the Java. Beans components. Server creates a local database of distributors. When an order is placed, suborders are sent to one or more distributors. 98