Home

The Java™ Web Services Tutorial

1. Find orgs with names that contain qString QUERYING A REGISTRY BulkResponse response bqm findOrganizations findQualifiers namePatterns null null null null Collection orgs response getCollection Finding Organizations by Classification To find organizations by classification you establish the classification within a particular classification scheme and then specify the classification as an argu ment to the findOrganizations method The following code fragment finds all organizations that correspond to a particu lar classification within the NAICS taxonomy You can find the NAICS codes at http ww census gov epcd naics naicscod txt The NAICS taxonomy has a well known universally unique identifier UUID that is defined by the UDDI specification The getRegistryObject method finds an object based upon its key See Creating an Organization page 186 for more information about keys String uuid_naics uuid C B9FE13 179F 413D 8A5B 5004DB8E5BB2 ClassificationScheme cScheme ClassificationScheme bqm getRegistryObject uuid_naics LifeCycleManager CLASSIFICATION_SCHEME InternationalString sn blcm createInternationalString All Other Specialty Food Stores String sv 445299 Classification classification blcm createClassification cScheme sn sv Collection lt Classification gt classifications new ArrayList lt Classification gt Q classifications add classification BulkResponse resp
2. 2 In an XML file define a taxonomy structure that is compliant with the JAXR Predefined Concepts DTD Enter the Classi ficationScheme ele ment in your taxonomy XML file by specifying the returned key ID value as the id attribute and the name as the name attribute For the foregoing code fragment for example the opening tag for the JAXRClassifica tionScheme element looks something like this all on one line lt JAXRClassi ficationScheme id uuid nnnnannnn nnnn nnnn nnnn nnnannnnnnnnn name MyScheme gt The ClassificationScheme id must be a universally unique identifier UUID 3 Enter each JAXRConcept element in your taxonomy XML file by specify ing the following four attributes in this order a id is the JAXRClassificationScheme id value followed by a sepa rator followed by the code of the JAXRConcept element b name is the name of the JAXRConcept element c parent is the immediate parent id either the ClassificationScheme id or that of the parent JAXRConcept d code is the JAXRConcept element code value The first JAXRConcept element in the naics xm1 file looks like this all on one line lt JAXRConcept jd uuid COB9FE13 179F 413D 8A5B 5004DB8E5BB2 11 name Agriculture Forestry Fishing and Hunting parent uuid CQB9FE13 179F 413D 8A5B 5004DB8E5BB2 code 11 gt lt JAXRConcept gt USING TAXONOMIES IN JAXR CLIENTS 4 To add the user defined taxonomy structure to the JAXR provider speci
3. The Java Web Services Tutonal ForJava Web Services Developer s Pack v2 0 February 17 2006 Copyright 2006 Sun Microsystems Inc 4150 Network Circle Santa Clara California 95054 U S A All rights reserved U S Government Rights Commercial software Government users are subject to the Sun Microsystems Inc standard license agreement and applicable provisions of the FAR and its supple ments This distribution may include materials developed by third parties Sun Sun Microsystems the Sun logo Java J2EE JavaServer Pages Enterprise JavaBeans Java Naming and Directory Interface EJB JSP J2EE J2SE and the Java Coffee Cup logo are trademarks or registered trademarks of Sun Microsystems Inc in the U S and other countries Unless otherwise licensed software code in all technical materials herein including articles FAQs sam ples is provided under this License Products covered by and information contained in this service manual are controlled by U S Export Con trol laws and may be subject to the export or import laws in other countries Nuclear missile chemical biological weapons or nuclear maritime end uses or end users whether direct or indirect are strictly pro hibited Export or reexport to countries subject to U S embargo or to entities identified on U S export exclusion lists including but not limited to the denied persons and specially designated nationals lists is strictly prohibited DOCUM
4. WebMethod public String sayHello String name return message name Building the Service To build HelloService in a terminal window go to the lt INSTALL gt javaeetutorial5 examples jaxws helloservice directory and type the following asant build The build task command executes these asant subtasks e compile service xx BUILDING WEB SERVICES WITH JAX WS The compile service Task This asant task compiles Hello java writing the class files to the build subdi rectory It then calls the wsgen tool to generate JAX WS portable artifacts used by the web service The equivalent command line command is as follows wsgen d build s build classpath build helloservice endpoint Hello The d flag specifies the output location of generated class files The s flag specifies the output location of generated source files The classpath flag specifies the location of the input files in this case the endpoint implmentation class helloservice endpoint Hel lo Packaging and Deploying the Service You package and deploy the service using asant Upon deployment the Application Server and the JAX WS runtime generate any additional artifacts required for web service invocation including the WSDL file Packaging and Deploying the Service with asant To package and deploy the hel loservice example follow these steps 1 In a terminal window go to lt INSTALL gt javaeetutorial5 examples jaxws hel loservice 2 R
5. Now you have the SOAPHeader object header that contains a SOAPHeaderE1e ment object whose content is order Adding Content to the SOAPPart Object If the content you want to send is in a file SAAJ provides an easy way to add it directly to the SOAPPart object This means that you do not access the SOAPBody object and build the XML content yourself as you did in the preceding section ADDING CONTENT TO THE SOAPPART OBJECT To add a file directly to the SOAPPart object you use a javax xm trans form Source object from JAXP the Java API for XML Processing There are three types of Source objects SAXSource DOMSource and StreamSource A StreamSource object holds an XML document in text form SAXSource and DOMSource objects hold content along with the instructions for transforming the content into an XML document The following code fragment uses the JAXP API to build a DOMSource object that is passed to the SOAPPart setContent method The first three lines of code get a DocumentBuilderFactory object and use it to create the Document Builder object builder Because SOAP messages use namespaces you should set the NamespaceAware property for the factory to true Then builder parses the content file to produce a Document object DocumentBuilderFactory dbFactory DocumentBui lderFactory newInstanceQ dbFactory setNamespaceAware true DocumentBuilder builder dbFactory newDocumentBui lderQ Document document builder parse fil
6. java lang String xsd integer java math BigInteger xsd int int xsd long long xsd short short xsd decimal java math BigDecimal xsd float float xsd double double xsd boolean boolean xsd byte byte xsd QName javax xml namespace QName xsd dateTime javax xml datatype XMLGregorianCalendar xsd base64Binary byte xsd hexBinary byte xsd unsignedInt long xsd unsignedShort int xsd unsignedByte short xsd time javax xml datatype XMLGregorianCalendar DEFAULT DATA TYPE BINDINGS Table 2 1 JAXB Mapping of XML Schema Built in Data Types Continued XML Schema Type Java Data Type javax xml1 datatype XMLGregorianCalendar 1g javax xml datatype XMLGregorianCalendar sanySimpleType java lang Object ranySimpleType java lang String duration javax xml datatype Duration NOTATION javax xml namespace QName J AXBElement When XML element information can not be inferred by the derived Java repre sentation of the XML content a JAXBElement object is provided This object has methods for getting and setting the object name and object value J ava to Schema Table 2 2 shows the default mapping of Java classes to XML data types Table 2 2 JAXB Mapping of XML Data Types to Java classes java lang String xs string
7. java math BigIn integer teger 9 java math BigDec imal decimal java util Calen dateTime dar java util Date dateTime BINDING BETWEEN XML SCHEMA AND JAVA CLASSES Table 2 2 JAXB Mapping of XML Data Types to Java classes Continued javax xml namespa ceONain xs QName java net URI string javax xml datatyp e XMLGregorian anySimpleType Calendar javax xml datatyp duration e Duration java lang Object anyType java awt Image base64Binary javax activa tion DataHandler base64Binary javax xml trans Far Source base64Binary java util UUID string Customizing J AXB Bindings Schema to ava Custom JAXB binding declarations also allow you to customize your generated JAXB classes beyond the XML specific constraints in an XML schema to include Java specific refinements such as class and package name mappings JAXB provides two ways to customize an XML schema e As inline annotations in a source XML schema e As declarations in an external binding customizations file that is passed to the JAXB binding compiler Code examples showing how to customize JAXB bindings are provided in Chap ter 3 JAVA TO SCHEMA J ava to Schema XML schema that is generated from Java objects can be customized with JAXB annotations 10 BINDING BETWEEN XML SCHEMA AND JAVA CLASSES 3 Using J AXB Tas chapter provides instructions for using the sa
8. Capturing the Event Steam The next step is to capture the event stream This is done in basically the same way as inthe event Sample EventParse java sample Filtering the Steam The final step is the filter the stream public boolean accept XMLStreamReader reader ifC reader isStartElementQ amp amp reader isEndElement return false else return true READNWRITE SAMPLE EVENTPRODUCERCONSUMER JAVA Running the Sample When you run the MyStreamFilter sample the class is compiled and the XML stream is parsed as events and returned to STDOUT For example an Author event is returned as follows EVENT TYPE C1 START_ELEMENT HAS NAME Author HAS NO TEXT HAS NO ATTRIBUTES EVENT TYPE 2 END_ELEMENT HAS NAME Author HAS NO TEXT Similarly a Cost event is returned as follows EVENT TYPE C1 START_ELEMENT HAS NAME Cost HAS NO TEXT HAS ATTRIBUTES ATTRIBUTE PREFIX ATTRIBUTE NAMESP null ATTRIBUTE NAME currency ATTRIBUTE VALUE USD ATTRIBUTE TYPE CDATA EVENT TYPE 2 END_ELEMENT HAS NAME Cost HAS NO TEXT See earlier in this chapter in the Iterator API and Reading XML Streams sections for a more detailed discussion of StAX event parsing readnwnite Sample EventProduc erC onsumerjava Located in the lt javaee tutorial home gt examples stax readnwrite direc tory EventProducerConsumer java demonstrates how to use a StAX parser simultaneously as both a producer and a consume
9. This section describes how JAXB represents XML content as Java objects Java Representation of XML Schema JAXB supports the grouping of generated classes in Java packages A package comprises e A Java class name is derived from the XML element name or specified by a binding customization e An ObjectFactory class is a factory that is used to return instances of a bound Java class Binding XML Schemas This section describes the default XML to Java bindings used by JAXB All of these bindings can be overridden on global or case by case levels by means of a custom binding declaration See the JAXB Specification for complete informa tion about the default JAXB bindings Simple Type Definitions A schema component using a simple type definition typically binds to a Java property Since there are different kinds of such schema components the follow ing Java property attributes common to the schema components include e Base type e Collection type if any e Predicate The rest of the Java property attributes are specified in the schema component using the simple type definition BINDING BETWEEN XML SCHEMA AND JAVA CLASSES Default Data Type Bindings Schema to J ava The Java language provides a richer set of data type than XML schema Table 2 1 lists the mapping of XML data types to Java data types in JAXB Table 2 1 JAXB Mapping of XML Schema Built in Data Types XML Schema Type xsd string Java Data Type
10. gt lt jxb nameXm1Transform gt lt jxb schemaBindings gt By comparison the syntax used in po xsd for the Datatype Converter example is lt xsd annotation gt lt xsd appinfo gt lt jxb globalBindings lt binding_declarations gt lt jxb schemaBindings gt lt binding_declarations gt lt jxb schemaBindings gt lt xsd appinfo gt lt xsd annotation gt FIX COLLIDES EXAMPLE Class Declarations The class level binding declarations in bindings xjb differ from the analogous declarations in po xsd for the Datatype Converter example in two ways e As with all other binding declarations in bindings xjb you do not need to embed your customizations in schema lt xsd appinfo gt elements e You must specify the schema node to which the customization will be applied The general syntax for this type of declaration is lt jxb bindings node lt node_type gt name lt node_name gt gt For example the following code shows binding declarations for the complex Type named USAddress lt jxb bindings node xs complexType name USAddress gt lt jxb class gt lt jxb javadoc gt lt CDATA First line of documentation for a lt b gt USAddress lt b gt gt lt jxb javadoc gt lt jxb class gt lt jxb bindings node xs element name name gt lt jxb property name toName gt lt jxb bindings gt lt jxb bindings node xs element name zip gt lt jxb property name zipCode gt
11. lt jxb bindings gt lt jxb bindings gt lt node xs complexType name USAddress gt Note in this example that USAddress is the parent of the child elements name and zip and therefore a lt jxb bindings gt tag encloses the bindings declarations for the child elements as well as the class level javadoc declaration Fix Collides Example The Fix Collides example illustrates how to resolve name conflicts that is places in which a declaration in a source schema uses the same name as another declaration in that schema namespace collisions or places in which a declara tion uses a name that does translate by default to a legal Java name 59 60 USING JAXB Note Many name collisions can occur because XSD Part introduces six unique symbol spaces based on type while Java only has only one There is a symbols space for type definitions elements attributes and group definitions As a result a valid XML schema can use the exact same name for both a type definition and a glo bal element declaration For the purposes of this example it is recommended that you remove the bind ing parameter to the xjc task in the build xml file in the lt INSTALL gt exam ples jaxb fix collides directory to display the error output generated by the xjc compiler The XML schema for the Fix Collides example xsd contains deliberate name conflicts Like the External Customize example the Fix Collides example uses an external
12. lt city gt Beverly Hills lt city gt lt state gt CA lt state gt lt Z1p gt 90210 lt zip gt lt bi11To gt lt items gt lt item partNum 242 NO gt lt productName gt Nosferatu Special Edition 1929 lt productName gt lt quantity gt 5 lt quantity gt lt USPrice gt 19 99 lt USPrice gt lt item gt lt item partNum 242 MU gt lt productName gt The Mummy 1959 lt productName gt lt quantity gt 3 lt quantity gt lt USPrice gt 19 98 lt USPrice gt lt item gt lt item partNum 242 GZ gt lt productName gt Godzilla and Mothra Battle for Earth Godzilla vs King Ghidora lt productName gt lt quantity gt 3 lt quantity gt lt USPrice gt 27 95 lt USPrice gt lt item gt lt items gt lt purchaseOrder gt Unmarshal Validate Example The Unmarshal Validate example demonstrates how to enable validation during unmarshalling Unmarshal Time Validation Note that JAXB provides functions for validation during unmarshalling but not during marshalling Validation is explained in more detail in More About Validation page 4 1 The lt INSTALL gt examples jaxb unmarshal validate Main java class declares imports for three standard Java classes plus seven JAXB binding framework classes and the primer po package import java io FileInputStream import java io IOException import java math BigDecimal import javax xml bind JAXBContext 33 USING JAXB import javax xml bind JAXBExceptio
13. ty 180 com sun xml registry ht tps proxyPassword connection property 180 com sun xml registry ht tps proxyPort connection proper ty 180 com sun xml registry ht tps proxyUserName connection property 180 com sun xml registry useCache connection property 180 com sun xml registry userTax onomyFilenames connection prop erty 180 197 concepts in user defined classification schemes 194 publishing with JAXR 190 204 removing with JAXR 205 using to create classifications with JAXR 188 connection factories JAXR creating 177 Connection interface JAXR 173 177 connection properties JAXR 178 examples 177 ConnectionFactory class JAXR 177 connections JAXR creating 177 setting properties 177 connections SAAJ 122 closing 132 point to point 131 country codes ISO 3166 181 createClassification method 188 195 createClassificationScheme method 195 createExternalLink method 195 createOrganization method 187 createPostalAddress method 198 createService method 189 createServiceBinding method 189 D deleteOrganizations method 193 detachNode method 126 Detail interface 148 DetailEntry interface 148 DOM SAAJ and 122 136 162 E ebXML registries 172 173 encrypting SOAP messages 247 end to end security 234 examples JAXR Java EE application 206 simple 199 required software xi SAAJ attachments 166 DOM 162 headers 160 request response 153 SOAP faults 168 setting build properties xi web services Xvi F f
14. uring Application Specific Message Security page 244 How Does WSS Work in the Application Server Web services deployed on the Application Server are secured by binding SOAP layer message security providers and message protection policies to the contain ers in which the applications are deployed or to web service endpoints served by the applications SOAP layer message security functionality is configured in the client side containers of the Application Server by binding SOAP layer message security providers and message protection policies to the client containers or to the portable service references declared by client applications When the Application Server is installed SOAP layer message security provid ers are configured in the client and server side containers of the Application USING THE APPLICATION SERVER MESSAGE SECURITY IMPLEMENTATION Server where they are available for binding for use by the containers or by indi vidual applications or clients deployed in the containers During installation the providers are configured with a simple message protection policy that if bound to a container or to an application or client in a container would cause the source of the content in all request and response messages to be authenticated by XML digital signature By default message layer security is disabled on the Application Server To con figure message layer security at the Application Server level read Configuring the Appl
15. writeAttributeC href http frob com writeEndElement writeEndElement writeEndElement writeEndElement writeEndDocument flushQ closeQ Running the Sample When you run the CursorWriter sample the class is compiled and the XML stream is parsed as events and written to a file named CursorWriter Output lt all elements here are explicitly in the HTML namespace gt lt xml version 1 0 encoding utf 8 gt lt html html xmins html http ww w3 org TR REC htm140 gt lt html head gt lt html title gt Frobnostication lt html1 title gt lt html head gt lt html body gt lt html p gt Moved to lt html a href http frob com gt here lt html a gt lt html p gt lt htm1 body gt lt html html gt Note that in the actual CursorWriter Output file this stream is written without any linebreaks the breaks have been added here to make the listing easier to read In this example as with the object stream in the event Sample Event Parse java sample the namespace prefix is added to both the opening and clos ing HTML tags This is not required by the StAX specification but it is good practice when the final scope of the output stream is not definitively known 116 STREAMING API FOR XML Further Information For more information about StAX see Java Community Process page http jcp org en jsr detai1 id 173 W3C Recommendation Extensible Markup Language X
16. FileInputStream filename when XMLStreamReader is created it is positioned at START_DOCUMENT event int eventType xmlr getEventTypeQ printEventType eventType printStartDocument xmlr check if there aremore eventsinthe input stream whi leCxmIr hasNextQ eventType xmlr next printEventType eventType these functionsprints the information about theparticular event by calling relevant function printStartElement Cxmlr printEndElement xm1r printText xmlr 103 104 STREAMING API FOR XML printPIDataCxmlr printComment xml r Note that next Q just returns an integer constant corresponding to the event underlying the current cursor location The application calls the relevant function to get more information related to the underlying event There are various acces sor methods which can be called when the cursor is at particular event Retuming String Representations Because the next method only returns integers corresponding to underlying event types you typically need to map these integers to string representations of the events for example public final staticString getEventTypeStringCinteventType switch eventType case XMLEvent START_ELEMENT return START_ELEMENT case XMLEvent END_ELEMENT return END_ELEMENT case XMLEvent PROCESSING_INSTRUCTION return PROCESSING_INSTRUCTION case XMLEvent CHARACTERS return CHARACTERS case XMLEvent CO
17. SOAP Version 1 2 Part 2 Adjuncts http www w3 org TR soapl2 part2 WS I Basic Profile http ww ws i org Profi les BasicProfile 1 1 html WS I Attachments Profile http ww ws i org Profi les AttachmentsProfile htm1 SOAP Message Transmission Optimization Mechanism MTOM http www w3 org TR soap12 mtom XML binary Optimized Packaging XOP http www w3 org TR xop10 JAXM web site http java sun com xm1 jaxm 6 Java API for XML Registries Tue Java API for XML Registries JAXR provides a uniform and standard Java API for accessing various kinds of XML registries After providing a brief overview of JAXR this chapter describes how to imple ment a JAXR client to publish an organization and its web services to a registry and to query a registry to find organizations and services Finally it explains how to run the examples provided with this tutorial and offers links to more informa tion on JAXR Overview of J AXR This section provides a brief overview of JAXR It covers the following topics e What is a registry What is JAXR e JAXR architecture What Is a Registry An XML registry is an infrastructure that enables the building deployment and discovery of web services It is a neutral third party that facilitates dynamic and 171 172 JAVA API FOR XML REGISTRIES loosely coupled business to business B2B interactions A registry is available to organizations as a shared resource often i
18. binding declarations file binding xjb to define the JAXB binding customiza tions e The example xsd Schema e Looking at the Conflicts e Output From Running the ant Task Without Using a Binding Declarations File e The binding xjb Declarations File e Resolving the Conflicts in example xsd The example xsd Schema The XML schema lt INSTALL gt examples jaxb fix collides example xsd used in the Fix Collides example illustrates common name con flicts encountered when attempting to bind XML names to unique Java identifi ers in a Java package The schema declarations that result in name conflicts are highlighted in bold below lt xs schema xmIns xs http www w3 org 2001 XMLSchema xmIns jxb http java sun com xml ns jaxb jxb version 1 Q gt lt xs element name Class type xs int gt lt xs element name FooBar type FooBar gt lt xs complexType name FooBar gt lt xsS Sequence gt lt xs element name foo type xs int gt lt xs element ref Class gt FIX COLLIDES EXAMPLE 61 lt xs element name zip type xs integer gt lt xs Sequence gt lt xS attribute name zip type xs string gt lt xs complexType gt lt xs schema gt Looking at the Conflicts The first conflict in example xsd is the declaration of the element name Class lt xs element name Class type xs int gt Class is a reserved word in Java and while
19. declaration provides a way to customize the translation of XML datatypes to and from Java datatypes XML provides more datatypes than Java and so the lt javaType gt declaration lets you specify custom datatype bind ings when the default JAXB binding cannot sufficiently represent your schema The target Java datatype can be a Java built in datatype or an application specific Java datatype If an application specific datatype is used as the target your implementation must also provide parse and print methods for unmarshalling and marshalling data To this end the JAXB specification supports a parseMethod and printMethod e The parseMethod is called during unmarshalling to convert a string from the input document into a value of the target Java datatype e The printMethod is called during marshalling to convert a value of the tar get type into a lexical representation 46 USING JAXB If you prefer to define your own datatype conversions JAXB defines a static class DatatypeConverter to assist in the parsing and printing of valid lexical representations of the XML Schema built in datatypes The syntax for the lt javaType gt customization is lt javaType name javaType xmlType xmlType hasNsContext true false parseMethod parseMethod printMethod printMethod gt e name is the Java datatype to which xm1Type is to be bound e xmlType is the name of the XML Schema datatype to which j
20. envelopedSignature xml is in the same directory To run the example execute the following command from the lt JWSDP_HOME gt xmldsig samples validate directory ant 222 JAVA XML DIGITAL SIGNATURE API The sample program will validate the signature in the file envelopedSigna ture xm1 in the current working directory To validate a different signature run the following command ant Dsample args Signature xm1 where signature xm1 is the pathname of the file Validating an XML Signature This example shows you how to validate an XML Signature using the JSR 105 API The example uses DOM the Document Object Model to parse an XML document containing a Signature element and a JSR 105 DOM implementation to validate the signature Instantiating the Doc ument that Contains the Signature First we use a JAXP DocumentBuilderFactory to parse the XML document containing the Signature An application obtains the default implementation for DocumentBui lderFactory by calling the following line of code DocumentBuilderFactory dbf DocumentBui lderFactory newInstance We must also make the factory namespace aware dbf setNamespaceAware true Next we use the factory to get an instance of a DocumentBui Ider which is used to parse the document DocumentBuilder builder dbf newDocumentBui lderQ Document doc builder parse new FileInputStream argv Specifying the Signature Hementto be Validated We need t
21. first occurrence of terms URLs code examples file names path names tool names monospace application names programming language keywords tag interface class method and field names properties italic monospace Variables in code file paths and URLs xiv ABOUT THIS TUTORIAL Table 2 Typographical Conventions Feedback Please send comments broken link reports errors suggestions and questions about this tutorial to the tutorial team at users jwsdp dev java net l Building Web Services with J AX WS J AX WS stands for Java API for XML Web Services JAX WS is a technology for building web services and clients that communicate using XML JAX WS allows developers to write message oriented as well as RPC oriented web ser vices In JAX WS 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 Although SOAP messages are complex the JAX WS API hides this complexity from the application developer On the server side the developer specifies the remote procedures by defining methods in an interface written in the Java pro gramming language The developer also codes one or more classes that imple ment those methods Client programs are also easy to code A client c
22. in jars available to the JRE 4 Use the platform default XMLInputFactory instance After getting a reference to an appropriate XMLInputFactory an application can use the factory to configure and create stream instances Table 4 4 lists the prop 89 90 STREAMING API FOR XML erties supported by XMLInputFactory See the StAX specification for a more detailed listing Table 4 4 XMLInputFactory Properties Property javax xml stream is Validating Description Turns on implementation specific validation javax xml stream isCoalescing Required Requires the processor to coalesce adjacent character data javax xml stream isNamespaceAware Turns off namespace support All implementations must support namespaces supporting non namespace aware documents is optional javax xml stream isReplacingEntityReferences Required Requires the processor to replace inter nal entity references with their replacement value and report them as characters or the set of events that describe the entity javax xml stream isSupportingExternalEntities Required Requires the processor to resolve exter nal parsed entities javax xml stream reporter Required Sets and gets the implementation of the XMLReporter javax xml stream resolver Required Sets and gets the implementation of the XMLResolver interface javax xml stream allocator XMLOutputFac tory Required Sets gets the implementation o
23. lt JWSDP_HOME gt xws security samples directory of your Java WSDP installation or at http java sun com webservices docs 2 0 xws security samples htm online e Visit the XWSS home page at http java sun com webservices xwss FURTHER INFORMATION 251 e Take the Sun training class titled Developing Secure Java Web Services To sign up go to https ww sun com training catalog java web_services html Further Information e Java 2 Standard Edition v 1 5 0 Security http java sun com j2se 1 5 0 docs guide security index html Java EE 5 Specification at http java sun com j2ee download html platformspec e Java Web Services Developer Pack Tutorial at http java sun com webservices docs 1 6 tutorial doc index htm The Developer s Guide for the Application Server contains information on developing applications specifically for deployment onto the Application Server As of this writing this document is available for viewing at http docs sun com app docs doc 819 3659 e The Administration Guide for the Application Server includes information on setting security settings for the Application Server As of this writing this document was available for viewing at http docs sun com app docs doc 819 3658 e The Application Deployment Guide for the Application Server is available as of this writing at http docs sun com app docs doc 819 3660 e Web Services for Java EE JSR 109 at http jcp org aboutJava co
24. page 240 discusses the challenges threats and coun termeasures in a bit more detail Security Challenges Threats and Countemeasures The WS I document titled Security Challenges Threats and Countermeasures can be read in its entirety at http ww ws i org Profi les BasicSecu rity SecurityChallenges 1 0 pdf Table 8 1 attempts to summarize many of the threats and countermeasures as an introduction to this document Table 8 1 Security Challenges Threats and Countermeasures Challenge Threats Countermeasures HTTPS with X 509 server authenti cation HTTP client authentication Basic or Digest HTTPS with X 509 mutual authenti cation of server and user agent OASIS SOAP Message Security falsified messages man Peer Identification and in the middle principal Authentication spoofing forged claims replay of message parts USING MESSAGE SECURITY WITH JAVA EE Table 8 1 Security Challenges Threats and Countermeasures Continued Challenge Data Origin Identifica tion and Authentication Threats Countermeasures falsified messages man in the middle principal spoofing forged claims replay of message parts OASIS SOAP Message Security MIME with XML Signature XML Encryption XML Signature Data Integrity includ ing Transport Data Integ rity and SOAP Message message alteration replay SSL TLS with encryption enabled XML Signatures as profiled in Integrity OASIS SOAP Message
25. sage could not be processed because of a problem in the SOAPBody object the SOAPFau1t object must contain a Detail object that gives details about the problem If a SOAPFau1t object does not contain a Detail object it can be assumed that the SOAPBody object was processed successfully Creating and Populating a SOAPFault Object You have seen how to add content to a SOAPBody object this section walks you through adding a SOAPFault object to a SOAPBody object and then adding its constituent parts As with adding content the first step is to access the SOAPBody object SOAPBody body message getSOAPBody With the SOAPBody object body in hand you can use it to create a SOAPFault object The following line of code creates a SOAPFault object and adds it to body SOAPFault fault body addFaultQ The SOAPFault interface provides convenience methods that create an element add the new element to the SOAPFau1t object and add a text node all in one operation For example in the following lines of SOAP 1 1 code the method setFaultCode creates a faultcode element adds it to fault and adds a Text 147 148 SOAP WITH ATTACHMENTS API FOR JAVA node with the value SOAP ENV Server by specifying a default prefix and the namespace URI for a SOAP envelope QName faultName new QName SOAPConstants URI_NS_SOAP_ENVELOPE Server fault setFaultCode faultName fault setFaultActorC http gizmos com orders fault setFaultStri
26. the actor attribute requires that there be an implementation such as a messaging provider service to route the message from one actor to the next 141 142 SOAP WITH ATTACHMENTS API FOR JAVA An actor is identified by its URI For example the following line of code in which orderHeader is a SOAPHeaderElement object sets the actor to the given URL orderHeader setActor http gizmos com orders Additional actors can be set in their own SOAPHeaderElement objects The fol lowing code fragment first uses the SOAPMessage object message to get its SOAP Header object header Then header creates four SOAPHeaderElement objects each of which sets its actor attribute SOAPHeader header message getSOAPHeader SOAPFactory soapFactory SOAPFactory newInstance String nameSpace ns String nameSpaceURI http gizmos com NSURI QName order new QName nameSpaceURI orderDesk nameSpace SOAPHeaderElement orderHeader header addHeaderElement order orderHeader setActor http gizmos com orders QName shipping new QName nameSpaceURI shippingDesk nameSpace SOAPHeaderElement shippingHeader header addHeaderE 1ement shipping shippingHeader setActor http gizmos com shipping QName confirmation new QName nameSpaceURI confirmationDesk nameSpace SOAPHeaderElement confirmationHeader header addHeaderElement confirmation confi rmationHeader setActor http gizmos com
27. the generated implementation classes should be represented internally as vectors Note that the class name you specify for collectionType must implement java util List and be callable by newInstance e Setting fixedAttributeAsConstantProperty to true indicates that all fixed attributes should be bound to Java constants By default fixed attributes are just mapped to either simple or collection property which ever is more appropriate e Please note that the JAXB implementation does not support the enable FailFastCheck attribute e If typesafeEnumBase to xsd string it would be a global way to specify that all simple type definitions deriving directly or indirectly from CUSTOMIZE INLINE EXAMPLE xsd string and having enumeration facets should be bound by default to a typesafe enum If typesafeEnumBase is set to an empty string no simple type definitions would ever be bound to a typesafe enum class by default The value of typesafeEnumBase can be any atomic simple type definition except xsd boolean and both binary types Note Using typesafe enums enables you to map schema enumeration values to Java constants which in turn makes it possible to do compares on Java constants rather than string values Schema Binding Declarations The following code shows the schema binding declarations in po xsd lt jxb schemaBindings gt lt jxb package name primer myPo gt lt jxb javadoc gt lt CDATA lt body gt Package level docum
28. together it adds import statements a main method and a try catch block with exception handling import javax xml soap import javax xml namespace QName import java util Iterator import java net URL public class Request public static void main String args try SOAPConnectionFactory soapConnectionFactory SOAPConnectionFactory newlInstance SOAPConnection connection soapConnectionFactory createConnection MessageFactory factory MessageFactory newlInstance SOAPMessage message factory createMessage SOAPHeader header message getSOAPHeader SOAPBody body message getSOAPBody header detachNode QName bodyName new QNameC http wombat ztrade com GetLastTradePrice m SOAPBodyElement bodyElement body addBodyE lement bodyName QName name new QName symbol SOAPElement symbol bodyElement addChi 1dE1ement name symbol addTextNode SUNW URL endpoint new URL C http wombat ztrade com quotes SOAPMessage response connection call message endpoint connection close SOAPBody soapBody response getSOAPBody MYUDDIPING JAVA Iterator iterator soapBody getChi 1dElements bodyName bodyElement SOAPBodyElement iterator next String lastPrice bodyElement getValueQ System out printC The last price for SUNW is System out printIn lastPrice catch Exception ex ex printStackTraceQ J For Reque
29. www w3 org 2001 XMLSchema gt lt jxb bindings schemaLocation po xsd node xs schema gt lt binding_declarations gt EXTERNAL CUSTOMIZE EXAMPLE lt jxb bindings gt lt schemaLocation po xsd node xs schema gt lt jxb bindings gt J AXB Version Number An XML file with a root element of lt jaxb bindings gt is considered an external binding file The root element must specify the JAXB version attribute with which its binding declarations must comply specifically the root lt jxb bind ings gt element must contain either a lt jxb version gt declaration or a version attribute By contrast when making binding declarations inline the JAXB ver sion number is made as attribute of the lt xsd schema gt declaration lt xsd schema xmIns xsd http www w3 org 2001 XMLSchema xmIns jxb http java sun com xml1 ns jaxb jxb version 1 0 gt Namespace Declarations As shown in JAXB Version Namespace and Schema Attributes page 56 the namespace declarations in the external binding declarations file include both the JAXB namespace and the XMLSchema namespace Note that the prefixes used in this example could in fact be anything you want the important thing is to con sistently use whatever prefixes you define here in subsequent declarations in the file Schema Name and Schema Node The fourth line of the code in JAXB Version Namespace and Schema Attributes page 56 specifies the name of the schema to which
30. 5 Click the download arrow for your platform Solaris or Windows 6 Choose the directory where you will download Java WSDP Install Java WSDP as follows 1 Go to the directory where you downloaded Java WSDP 1 5 2 Run the Java WSDP installer You can follow the instructions that are linked to from http java sun com webservices downloads 1 5 index html although these instructions refer to a newer version of Java WSDP 3 On the Select a Web Container page of the installer select No Web Con tainer 4 Choose a directory where you will install Java WSDP 5 Select either a Typical or a Custom installation If you select Custom remove the check marks from every checkbox you can except Java WSDP Registry Server You cannot remove the check marks from JAXB JAXP JAXR or SAAJ these technologies are required After the installation completes install the Registry Server in the Application Server as follows 1 Stop the Application Server if it is running 2 Copy the two WAR files in the directory lt JWSDP_HOME gt registry server webapps RegistryServer war and Xindice war to the follow ing directory lt JAVAEE_HOME gt domains domain1 autodep1oy 3 Start the Application Server Any user of a JAXR client can perform queries on a registry To add data to the registry or to update registry data however a user must obtain permission from the registry to access it To add or update data in the Java WSDP Registry Serve
31. Properties props setProperty javax xml registry queryManagerURL http localhost 8080 RegistryServer props setProperty javax xml registry 1lifeCycleManagerURL http localhost 8080 RegistryServer With the Application Server implementation of JAXR if the client is accessing a registry that is outside a firewall it must also specify proxy host and port infor mation for the network on which it is running For queries it may need to specify 178 JAVA API FOR XML REGISTRIES only the HTTP proxy host and port for updates it must specify the HTTPS proxy host and port props setProperty com sun xml registry http proxyHost myhost mydomain props setProperty com sun xml registry http proxyPort 8080 props setProperty com sun xml registry https proxyHost myhost mydomain props setProperty com sun xml registry https proxyPort 8080 The client then sets the properties for the connection factory and creates the con nection connFactory setProperties props Connection connection connFactory createConnectionQ The makeConnection method in the sample programs shows the steps used to create a JAXR connection Setting Connection Properties The implementation of JAXR in the Application Server allows you to set a num ber of properties on a JAXR connection Some of these are standard properties defined in the JAXR specification Other properties are specific to the implemen tation of JAXR
32. SOAPMessage method getAttachments and pass it a MIMEHeaders object containing the MIME headers you are interested in The following code fragment shows one of the ways to use the method setCon tent The Java Object in the first parameter can be a String a stream a javax xm l transform Source object or a javax activation DataHandler object The Java Object being added in the following code fragment is a String which is plain text so the second argument must be text plain The code 137 138 SOAP WITH ATTACHMENTS API FOR JAVA also sets a content identifier which can be used to identify this AttachmentPart object After you have added content to attachment you must add it to the SOAPMessage object something that is done in the last line String stringContent Update address for Sunny Skies Inc to 10 Upbeat Street Pleasant Grove CA 95439 attachment setContent stringContent text plain attachment setContentId update_address message addAttachmentPart attachment The attachment variable now represents an AttachmentPart object that con tains the string stringContent and has a header that contains the string text plain It also has a Content Id header with update_address as its value And attachment is now part of message The other two SOAPMessage createAttachment methods create an Attach mentPart object complete with content One is very similar to the Attachment Part setContent method in that it tak
33. Security Data Confidentiality including Transport Data Confidentiality and SOAP Message Confi dentiality SSL TSL with encryption enabled XML Signatures as profiled in OASIS SOAP Message Security confidentiality SSL TLS between the node that generated the request and the node that is guaranteeing Signing of nonce time stamp replay of message parts Message Uniqueness replay denial of service As you can see from the countermeasures that are recommended in the table and in the document the use of XML Encryption and XML Digital Signature to secure SOAP messages and attachments is strongly recommended by this orga nization Using Message Security with Java FE page 241 discusses some options for securing messages with Java EE Using Message Securty with Java EE Because message security is not yet a part of the Java EE platform and because message security is a very important component of web services security this section presents a brief introduction to using both the Application Server s Web Services Security WSS and the Java WSDP s XML and Web Services Security XWSS functionality e Using the Application Server Implementation page 242 e Using the Java WSDP XWSS Security Implementation page 247 Message Security 241 242 SECURING WEB SERVICES Using the Application Server Message Security Implementation The Sun Java System Application Server uses Web Services Security W
34. Sender lt env Value gt lt env Code gt lt env Reason gt lt env Text xml lang en US gt Message does not have necessary info lt env Text gt lt env Reason gt lt env Role gt http gizmos com order lt env Role gt lt env Detai I gt lt PO order xmins PO http gizmos com orders gt Quantity element does not have a value lt PO order gt lt PO confirmation xmlIns PO0 http gizmos com confirm gt Incomplete address no zip code lt PO confirmation gt lt env Detai 1 gt lt env Fault gt lt env Body gt lt env Envelope gt SOAP fault contains Fault code http www w3 org 2003 05 soap envelope Sender Local name Sender Namespace prefix env bound to 170 SOAP WITH ATTACHMENTS API FOR JAVA http www w3 org 2003 05 soap envelope Fault reason text Message does not have necessary info Fault role http gizmos com order Detail entry Quantity element does not have a value Detail entry Incomplete address no zip code Further Information For more information about SAAJ SOAP and WS I see the following SAAJ 1 3 specification available from http java sun com xml downloads saaj htm SAAJ web site http java sun com xm1 saaj Simple Object Access Protocol SOAP 1 1 http www w3 org TR 2000 NOTE SOAP 20000508 SOAP Version 1 2 Part 0 Primer http www w3 org TR soapl12 part0 SOAP Version 1 2 Part 1 Messaging Framework http www w3 org TR soapl2 part1
35. Why Customize 35 Customization Overview 36 Customize Inline Example 49 Datatype Converter Example 55 External Customize Example 56 Fix Collides Example 59 Bind Choice Example 64 Java toSchema Examples 66 j2s create marshal Example 66 j2s xmlAccessorOrder Example 66 j2s xmlAdapter field Example 69 j2s xmlAttribute field Example 72 j2s xmlRootElement Example 73 j2s xmlSchemaType class Example 73 j2s xmlType Example 74 Chapter 4 Chapter 5 CONTENTS Streaming API for XML 000 e eee 77 Why StAX 77 Streaming Versus DOM 78 Pull Parsing Versus Push Parsing 79 StAX Use Cases 79 Comparing StAX to Other JAXP APIs 80 StAX API 81 Cursor API 81 Iterator API 82 Choosing Between Cursor and Iterator APIs 87 Using StAX 89 StAX Factory Classes 89 Resources Namespaces and Errors 91 Reading XML Streams 92 Writing XML Streams 95 Sun s Streaming Parser Implementation 97 Reporting CDATA Events 97 SJSXP Factories Implementation 98 Sample Code 99 Sample Code Organization 99 Configuring Your Environment for Running the Samples 100 Running the Samples 101 Sample XML Document 102 cursor Sample CursorParse java 103 cursor2event Sample CursorApproachEventObject java 105 event Sample EventParse java 106 filter Sample MyStreamFilter java 109 readnwrite Sample EventProducerConsumer java 111 writer Sample CursorWriter java 114 Further Information 116 SOAP with Attachments API forJava 117 Overvi
36. Xml Type propOrder mapping annotations in Java classes to control the order in which XML content is marshalled unmarshaled by a Java type j2s xmlAccessorOrder Illustrates how to use the interface Xm Adapter and the annota tion XmlJavaTypeAdapter to provide a a custom mapping of XML content into and out of a HashMap field that uses an int as the key and a string as the value j2s xmlAdapter field Illustrates how to use the annotation XmlAttribute to define a property or field to be handled as an XML attribute j2s xmlAttribute field Illustrates how to use the annotation XmlRootElement to define j2s xmlRootElement an XML element name for the XML schema type of the corre sponding class j2s xmlSchemaType Illustrates how to use the annotation XmlSchemaType to cus class tomize the mapping of a property or field to an XML built in type Illustrates how to use the annotation XmlType to map a class or desea pe enum type to an XML schema type Each Basic and Customize example directory contains several base files e po xsd is the XML schema you will use as input to the JAXB binding compiler and from which schema derived JAXB Java classes will be gen erated For the Customize Inline and Datatype Converter examples this file contains inline binding customizations Note that the Fix Collides example uses example xsd rather than po xsd e po xml is the Purchase Order XML file containing s
37. Yoga lt Title gt lt ISBN gt 81 40 34319 4 lt ISBN gt lt Cost currency INR gt 11 50 lt Cost gt lt Book gt lt BookCatalogue gt This document would be parsed into eighteen primary and secondary events as shown below Note that secondary events shown in curly braces are typi cally accessed from a primary event rather than directly Table 4 3 Sample Iterator API Event Mapping Element Attribute Event version 1 0 StartDocument isCData false data n IswhiteSpace true Characters qname BookCatalogue http www publishing org attributes null namespaces BookCatalogue gt http www publishing org StartE ement qname Book attributes null namespaces null StartEl lement qname Title attributes null namespaces null StartE lement isCData false data Yogasana Vijnana the Science of Yoga n t IsWhiteSpace false Characters qname Title namespaces null EndElement 86 STREAMING API FOR XML Table 4 3 Sample Iterator API Event Mapping Continued Element Attribute Event qname ISBN attributes null StartElement namespaces null isCData false data 81 40 34319 4 n t Characters IswWhiteSpace false qname ISBN EndElement namespaces null qname Cost attributes currency gt INR StartElement namespaces null isCData false data 11 50 n t Characte
38. actor is null works because the method getFaultActor returns null if a fault actor has not been set System out printInC SOAP fault contains System out printIn Fault code code toString System out printIn Local name code getLocalPart System out printIn Namespace prefix code getPrefix bound to code getNamespaceURI System out printIn Fault string string if C actor null System out printiInC Fault actor actor The final task is to retrieve the Detail object and get its DetailEntry objects The code uses the SOAPFault object newFault to retrieve the Detail object newDetail and then it uses newDetail to call the method getDetailEntries This method returns the java util Iterator object entries which contains all the DetailEntry objects in newDetail Not all SOAPFault objects are required to have a Detail object so the code tests to see whether newDetai1 is CODE EXAMPLES 151 nul1 If it is not the code prints the values of the Detai 1Entry objects as long as there are any Detail newDetail newFault getDetailQ if CnewDetail null Iterator entries newDetail getDetailEntries while C entries hasNext Q DetailEntry newEntry DetailEntry entries nextQ String value newEntry getValueQ System out printIn Detail entry value In summary you have seen how to add a SOAPFau1t object and its contents to a message as well as
39. bind DatatypeConverter parseInt printMethod javax xml bind DatatypeConverter printInt gt lt xsd appinfo gt lt xsd annotation gt lt xsd restriction base xsd integer gt 55 56 USING JAXB lt xsd minInclusive value 10000 gt lt xsd maxInclusive value 99999 gt lt xsd restriction gt lt xsd simpleType gt Extemal Customize Example The External Customize example is identical to the Datatype Converter example except that the binding declarations in the External Customize example are made by means of an external binding declarations file rather than inline in the source XML schema The binding customization file used in the External Customize example is lt INSTALL gt examples jaxb external customize binding xjb This section compares the customization declarations in bindings xjb with the analogous declarations used in the XML schema po xsd in the Datatype Con verter example The two sets of declarations achieve precisely the same results e JAXB Version Namespace and Schema Attributes e Global and Schema Binding Declarations e Class Declarations J AXB Version Namespace and Schema Atinibutes All JAXB binding declarations files must begin with e JAXB version number e Namespace declarations e Schema name and node The version namespace and schema declarations in bindings xjb are as fol lows lt jxb bindings version 1 0 xmIns jxb http java sun com xml ns jaxb xmIns xs http
40. binding xjb will be passed to the xjc binding compiler which will then resolve the conflicts in example xsd in the schema derived Java classes 63 64 USING JAXB Bind Choice Example The Bind Choice example shows how to bind a choice model group to a Java interface Like the External Customize and Fix Collides examples the Bind Choice example uses an external binding declarations file binding xjb to define the JAXB binding customization The schema declarations in lt INSTALL gt examples jaxb bind choice example xsd that will be globally changed are highlighted in bold below lt xs schema xmIns xs http www w3 org 2001 XMLSchema xmIns jxb http java sun com xml ns jaxb jxb version 1 0 gt lt xs element name FooBar gt lt xs complexType gt lt xs Sequence gt lt xs element name foo type xs int gt lt xs element ref Class gt lt xs choice gt lt xs element name phoneNumber type xs string gt lt xs element name speedDial type xs int gt lt xs choice gt lt xs group ref ModelGroupChoice gt lt xs Sequence gt lt xSiattribute name zip type xs string gt lt xs complexType gt lt xs element gt lt xS group name ModelGroupChoice gt lt xs choice gt lt xs element name bool type xs boolean gt lt xs element name comment type xs string gt lt xs element name value type xs int gt
41. confirmations QName billing new QName nameSpaceURI billingDesk nameSpace SOAPHeaderElement billingHeader header addHeaderElement billing billingHeader setActor http gizmos com billing The SOAPHeader interface provides two methods that return a java util Iter ator object over all the SOAPHeaderElement objects that have an actor that ADDING ATTRIBUTES matches the specified actor The first method examineHeaderElements returns an iterator over all the elements that have the specified actor java util Iterator headerElements header examineHeaderElements http gizmos com orders The second method extractHeaderElements not only returns an iterator over all the SOAPHeaderElement objects that have the specified actor attribute but also detaches them from the SOAPHeader object So for example after the order desk application did its work it would call extractHeaderElements to remove all the SOAPHeaderElement objects that applied to it java util Iterator headerElements header extractHeaderElements http gizmos com orders Each SOAPHeaderElement object can have only one actor attribute but the same actor can be an attribute for multiple SOAPHeaderElement objects Two additional SOAPHeader methods examineAllHeaderElements and extractAl 1HeaderElements allow you to examine or extract all the header elements whether or not they have an actor attribute For example you could use the follow
42. containing a SOAP fault element which gives you status information error information or both There can be only one SOAP fault element in a mes sage and it must be an entry in the SOAP body Furthermore if there is a SOAP fault element in the SOAP body there can be no other elements in the SOAP body This means that when you add a SOAP fault element you have effectively completed the construction of the SOAP body A SOAPFault object the representation of a SOAP fault element in the SAAJ API is similar to an Exception object in that it conveys information about a problem However a SOAPFau1t object is quite different in that it is an element in a message s SOAPBody object rather than part of the try catch mechanism used for Exception objects Also as part of the SOAPBody object which pro vides a simple means for sending mandatory information intended for the ulti mate recipient a SOAPFault object only reports status or error information It does not halt the execution of an application as an Exception object can If you are a client using the SAAJ API and are sending point to point messages the recipient of your message may add a SOAPFault object to the response to alert you to a problem For example if you sent an order with an incomplete address for where to send the order the service receiving the order might put a SOAPFault object in the return message telling you that part of the address was missing Another example of who
43. could also have been the following String endpoint http fabulous com gizmo order SOAPMessage response connection call request endpoint A web service implemented for request response messaging must return a response to any message it receives The response is a SOAPMessage object just as the request is a SOAPMessage object When the request message is an update the response is an acknowledgment that the update was received Such an acknowledgment implies that the update was successful Some messages may not require any response at all The service that gets such a message is still required to send back a response because one is needed to unblock the cal method In this case the response is not related to the content of the message it is simply a message to unblock the ca11 method Now that you have some background on SOAP messages and SOAP connec tions in the next section you will see how to use the SAAJ API Tutonal This tutorial walks you through how to use the SAAJ API First it covers the basics of creating and sending a simple SOAP message Then you will learn more details about adding content to messages including how to create SOAP faults and attributes Finally you will learn how to send a message and retrieve 124 SOAP WITH ATTACHMENTS API FOR JAVA the content of the response After going through this tutorial you will know how to perform the following tasks e Creating and sending a simple message e Ad
44. create the document But because DOMSrcExample makes the document the entire content of the message the document must already be in the form of a valid SOAP message and not just any XML document DOMEXAMPLE JAVA AND DOMSRCEXAMPLE JAVA 165 Running DOMExample and DOMSic Example To run DOMExample and DOMSrcExample you use the file build xm1 that is in the directory lt INSTALL gt javaeetutorial5 examples saaj dom This directory also contains several sample XML files you can use e domsrcl1 xml an example that has a SOAP header the contents of the HeaderExamp1le output and the body of a UDDI query e domsrc2 xml an example of a reply to a UDDI query specifically some sample output from the MyUddiPing example but with spaces added for readability e uddimsg xm1 similar to domsrc2 xm1 except that it is only the body of the message and contains no spaces e slide xml1 another file that consists only of a body but that contains spaces You can use any of these four files when you run DOMExample To run DOMExample use a command like the following asant run dom Dxml file uddimsg xml When you run DOMExample using the file uddimsg xm1 you will see output that begins like the following Running DOMExample Name is urn uddi org api_v2 businessList Attribute Attribute Attribute Attribute Attribute Attribute Attribute Attribute name is generic value is 2 0 name is operator value is www ibm com se
45. defined by the JAXR specification This level allows access to both UDDI and ebXML registries at a basic level At this release the JAXR provider supports access only to UDDI version 2 registries Currently no public UDDI registries exist However you can use the Java WSDP Registry Server a private UDDI version 2 registry that comes with release 1 5 of the Java Web Services Developer Pack Java WSDP JAXR ARCHITECTURE Service Registry an ebXML registry and repositry with a JAXR provider is available as part of the Sun Java Enterprise System J AXR Architec ture The high level architecture of JAXR consists of the following parts e A JAXR client This is a client program that uses the JAXR API to access a business registry via a JAXR provider e A JAXR provider This is an implementation of the JAXR API that pro vides access to a specific registry provider or to aclass of registry providers that are based on a common specification A JAXR provider implements two main packages e javax xml registry which consists of the API interfaces and classes that define the registry access interface e 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 RegistryObject interface Its subinter faces include Organization Service and ServiceBi
46. down load php 7011 wss saml interopl draft 11 doc A addChildElement method 128 addClassifications method 188 addExternalLink method 195 addServiceBindings method 189 addServices method 190 addTextNode method 128 AttachmentPart class 121 137 creating objects 137 headers 137 attachments 120 adding 137 SAAJ example 166 attributes SOAP envelope 129 SOAP header 141 XML elements 139 authentication for XML registries 186 B binding templates adding to an organization with JAXR 189 finding with JAXR 185 businesses contacts 187 creating with JAXR 186 Index finding by name with JAXR 182 202 using WSDL documents with JAXR 205 finding by classification with JAXR 183 202 keys 187 193 publishing with JAXR 190 removing with JAXR 193 202 saving with JAXR 202 204 BusinessLifeCycleManager inter face 173 181 186 BusinessQueryManager interface 173 181 C call method 122 123 132 capability levels JAXR 172 classification schemes finding with JAXR 188 ISO 3166 181 NAICS 181 202 postal address 195 203 publishing with JAXR 195 203 removing with JAXR 204 UNSPSC 181 253 254 INDEX user defined 194 classifications creating with JAXR 188 clients JAXR 173 examples 199 implementing 174 close method 132 com sun xml registry ht tp proxyHost connection property 179 com sun xml registry ht tp proxyPort connection property 179 com sun xml registry ht tps proxyHost connection proper
47. included in each example directory Configuring and Running the Samples The build xml file included in each example directory is an asant project file that when run automatically performs the following steps 1 Updates your CLASSPATH to include the necessary schema derived JAXB classes 2 For the Basic and Customize examples runs the JAXB binding compiler to generate JAXB Java classes from the XML source schema po xsd and puts the classes in a package named primer po For the Java to Schema examples runs schemagen the schema generator to generate XML schema from the annotated Java classes 15 16 USING JAXB 3 Compiles the schema derived JAXB classes or the annotated Java code 4 Runs the Main class for the example The schema derived JAXB classes and how they are bound to the source schema is described in About the Schema to Java Bindings page 19 The methods used for building and processing the Java content tree are described in Basic Examples page 29 J AXB Compiler Options The JAXB XJC schema binding compiler transforms or binds a source XML schema to a set of JAXB content classes in the Java programming language The compiler xjc is provided in two flavors in the Application Server xjc sh Solaris Linux and xjc bat Windows Both xjc sh and xjc bat take the same command line options You can display quick usage instructions by invok ing the scripts without any options or with the help switch The
48. is a concrete implementation of the abstract XMLSignatureFactory and KeyInfoFactory classes and is responsible for cre ating objects and algorithms that parse generate and validate XML Signatures and KeyInfo structures A concrete implementation of XMLSignatureFactory must provide support for each of the required algorithms as specified by the W3C recommendation for XML Signatures It may support other algorithms as defined by the W3C recommendation or other specifications JSR 105 leverages the JCA provider model for registering and loading XMLSig natureFactory and KeyInfoFactory implementations Each concrete XMLSignatureFactory or KeyInfoFactory implementation sup ports a specific XML mechanism type that identifies the XML processing mech anism that an implementation uses internally to parse and generate XML signature and KeyInfo structures This JSR supports one standard type DOM The XML Digital Signature API early access provider implementation that is bundled with Java WSDP supports the DOM mechanism Support for new stan dard types such as JOOM may be added in the future An XML Digital Signature API implementation should use underlying JCA engine classes such as java security Signature and java security Mes sageDigest to perform cryptographic operations In addition to the XMLSignatureFactory and KeyInfoFactory classes JSR 105 supports a service provider interface for transform and canonicalization algo rithms The Transfor
49. is the output that is returned if you run the ant task in the lt INSTALL gt examples jaxb fix collides directory without specifying the binding parameter to the xjc task in the build xm1 file echo Compiling the schema w o external binding file name collision errors expected xjc Compiling file C javaeetutorial5 examples jaxb fix collides example xsd xjc ERROR Attempt to create a property having the same name as the reserved word Class xjc line 14 of example xsd xjc ERROR A property with the same name Zip is generated from more than one schema component xjc line 17 of example xsd xjc ERROR Relevant to above error another one is generated from this schema component xjc line 15 of example xsd xjc ERROR A class interface with the same name generated FooBar is already in use xjc line 9 of example xsd xjc ERROR Relevant to above error another one is generated from here xjc line 18 of example xsd The binding xjb Declarations File The lt INSTALL gt examples jaxb fix collides binding xjb binding declara tions file resolves the conflicts in examples xsd by means of several customiza tions FIX COLLIDES EXAMPLE Resolving the Conflicts in example xsd The first conflict in example xsd using the Java reserved name Class for an element name is resolved in binding xjb with the lt class gt and lt property gt declarations on the schema element node Class lt jxb bindi
50. it You will see more about headers later Because all SOAPElement objects including SOAPHeader objects are derived from the Node interface you use the method Node detachNode to delete header header detachNode CREATING AND SENDING A SIMPLE MESSAGE Adding Content to the Body The SOAPBody object contains either content or a fault To add content to the body you normally create one or more SOAPBodyElement objects to hold the content You can also add subelements to the SOAPBodyElement objects by using the addChi 1dElement method For each element or child element you add con tent by using the addTextNode method When you create any new element you also need to create an associated javax xml namespace QName object so that it is uniquely identified Note You can use Name objects instead of QName objects Name objects are specific to the SAAJ API and you create them using either SOAPEnvelope methods or SOAPFactory methods However the Name interface may be deprecated at a future release The SOAPFactory class also lets you create XML elements when you are not creat ing an entire message or do not have access to a complete SOAPMessage object For example JAX RPC implementations often work with XML fragments rather than complete SOAPMessage objects Consequently they do not have access to a SOAPEn velope object and this makes using a SOAPFactory object to create Name objects very useful In addition to a method for creat
51. item targeted at the fault ing SOAP node is scoped with a data encod ing that the faulting node does not support Retrieving Fault Information Just as the SOAPFau1t interface provides convenience methods for adding infor mation it also provides convenience methods for retrieving that information 149 150 SOAP WITH ATTACHMENTS API FOR JAVA The following code fragment shows what you might write to retrieve fault infor mation from a message you received In the code fragment newMessage is the SOAPMessage object that has been sent to you Because a SOAPFau1t object must be part of the SOAPBody object the first step is to access the SOAPBody object Then the code tests to see whether the SOAPBody object contains a SOAPFault object If it does the code retrieves the SOAPFau1t object and uses it to retrieve its contents The convenience methods getFaultCode getFaultString and getFaultActor make retrieving the values very easy SOAPBody body newMessage getSOAPBody if body hasFaultQ SOAPFault newFault body getFaultQ QName code newFault getFaultCodeAsQName String string newFault getFaultStringQ String actor newFault getFaultActorQ To retrieve subcodes from a SOAP 1 2 fault call the method newFault get FaultSubcodes Next the code prints the values it has just retrieved Not all messages are required to have a fault actor so the code tests to see whether there is one Testing whether the variable
52. javaType gt Binding Declarations page 45 for more information lt globalBindings gt declarations are only valid in the annotation element of the top level schema element There can only be a single instance of a lt globalBi ndings gt declaration in any given schema or binding declarations file If one source schema includes or imports a second source schema the lt globalBind ings gt declaration must be declared in the first source schema Schema Binding Declarations Schema scope customizations are declared with lt schemaBindings gt The syntax for schema scope customizations is lt schemaBindings gt lt package gt package lt package gt lt nameXm1lTransform gt lt nameXmlTransform gt lt schemaBindings gt lt package name packageName lt javadoc gt lt javadoc gt lt package gt lt nameXm1Transform gt lt typeName suffix suffix prefix prefix gt lt elementName suffix suffix prefix prefix gt lt modelGroupName suffix suffix prefix prefix gt lt anonymousTypeName suffix suffix prefix prefix gt lt nameXm1Transform gt As shown above lt schemaBinding gt declarations include two subcomponents e lt package gt lt package gt specifies the name of the package and if desired the location of the API documentation for the schema derived classes 44 USING JAXB e lt nameXmlTransform g
53. lt Title gt lt Author gt J Krishnamurti lt Author gt lt Date gt 1954 lt Date gt lt ISBN gt 0 06 064831 7 lt ISBN gt lt Publisher gt Harper amp amp Row lt Publisher gt lt Cost currency USD gt 2 95 lt Cost gt lt Book gt lt BookCatalogue gt CURSOR SAMPLE CURSORPARSE JAVA cursor Sample CursorParse java Located in the lt javaee tutorial home gt examples stax cursor directory CursorParse java demonstrates using the StAX cursor API to read an XML document In this sample the application instructs the parser to read the next event in the XML input stream by calling lt code gt next lt code gt Note that lt code gt next lt code gt just returns an integer constant corresponding to underlying event where the parser is positioned The application needs to call the relevant function to get more information related to the underlying event You can imagine this approach as a virtual cursor moving across the XML input stream There are various accessor methods which can be called when that vir tual cursor is at particular event Stepping Through Events In this example the client application pulls the next event in the XML stream by calling the next method on the parser for example try for int i 0 i lt count i pass the file name allrelativeentity references will be resolved againstthis as base URI XMLStreamReader xml r xmlif createxXMLStreamReader filename new
54. lt JWSDP_HOME gt xm1dsig samples genenveloped directory The file on which it operates envelope xm1 is in the same directory It generates the file envelo pedSignature xml To compile and run this sample execute the following command from the lt JWSDP_HOME gt xm1dsig samples genenveloped directory ant GENENVELOPED EXAMPLE The sample program will generate an enveloped signature of the document in the file envelope xm1 and store it in the file envelopedSignature xm1 in the cur rent working directory Generating an XML Signature This example shows you how to generate an XML Signature using the XML Digital Signature API More specifically the example generates an enveloped XML Signature of an XML document An enveloped signature is a signature that is contained inside the content that it is signing The example uses DOM the Document Object Model to parse the XML document to be signed and a JSR 105 DOM implementation to generate the resulting signature A basic knowledge of XML Signatures and their different components is helpful for understanding this section See http ww w3 org TR xmldsig core for more information Instantiating the Documentto be Signed First we use a JAXP DocumentBui lderFactory to parse the XML document that we want to sign An application obtains the default implementation for Doc umentBui lderFactory by calling the following line of code DocumentBuilderFactory dbf DocumentBui lderFactory n
55. peuvent tre soumis au droit d autres pays dans le domaine des exportations et importations Les utilisations finales ou utilisateurs finaux pour des armes nucl aires des missiles des armes biologiques et chimiques ou du nucl aire maritime directe ment ou indirectement sont strictement interdites Les exportations ou r exportations vers des pays sous embargo des Etats Unis ou vers des entit s figurant sur les listes d exclusion d exportation am ricaines y compris mais de mani re non exclusive la liste de personnes qui font objet d un ordre de ne pas partic iper d une fa on directe ou indirecte aux exportations des produits ou des services qui sont r gi par la l gislation am ricaine en mati re de contr le des exportations U S Commerce Department s Table of Denial Orders et la liste de ressortissants sp cifiquement d sign s U S Treasury Department of Spe cially Designated Nationals and Blocked Persons sont rigoureusement interdites LA DOCUMENTATION EST FOURNIE EN L ETAT ET TOUTES AUTRES CONDITIONS DEC LARATIONS ET GARANTIES EXPRESSES OU TACITES SONT FORMELLEMENT EXCLUES DANS LA MESURE AUTORISEE PAR LA LOI APPLICABLE Y COMPRIS NOTAMMENT TOUTE GARANTIE IMPLICITE RELATIVE A LA QUALITE MARCHANDE A L APTITUDE A UNE UTILISATION PARTICULIERE OU A L ABSENCE DE CONTREFA ON Chapter 1 Chapter 2 Contents About This Tutorial 0 0 0 2 ce Who Should Use This Tutorial Prerequi
56. postal address scheme to a registry e JAXRPublishPostal java shows how to publish an organization with a postal address for its primary contact e JAXRQueryPostal java shows how to retrieve postal address data from an organization 200 JAVA API FOR XML REGISTRIES e JAXRDeleteScheme java shows how to delete a classification scheme from a registry e JAXRPublishConcept java shows how to publish a concept for a WSDL document e JAXRPublishHelloOrg java shows how to publish an organization with a service binding that refers to a WSDL document e JAXRDeleteConcept java shows how to delete a concept e JAXRGetMyObjects java lists all the objects that you own in a registry The lt INSTALL gt javaeetutorial5 examples jaxr simple directory also contains the following e A build xml file for the examples e A JAXRExamples properties file in the src subdirectory that supplies string values used by the sample programs e A file called postalconcepts xm1 that serves as the taxonomy file for the postal address examples Before You Compile the Examples Before you compile the examples edit the file lt INSTALL gt javaeetutorial5 examples jaxr simple src JAXRExamples properties as follows 1 If the Application Server where you installed the Registry Server is run ning on a system other than your own or if itis using a nondefault HTTP port change the following lines query url http localhost 8080 RegistryServer publ
57. process several requests as with an application server In fact it can be argued that the majority of XML business logic can benefit from stream processing and does not require the in memory maintenance of entire DOM trees PULL PARSING VERSUS PUSH PARSING Pull Parsing Versus Push Parsing Streaming pull parsing refers to a programming model in which a client applica tion calls methods on an XML parsing library when it needs to interact with an XML infoset that is the client only gets pulls XML data when it explicitly asks for it Streaming push parsing refers to a programming model in which an XML parser sends pushes XML data to the client as the parser encounters elements in an XML infoset that is the parser sends the data whether or not the client is ready to use it at that time Pull parsing provides several advantages over push parsing when working with XML streams e With pull parsing the client controls the application thread and can call methods on the parser when needed By contrast with push processing the parser controls the application thread and the client can only accept invo cations from the parser e Pull parsing libraries can be much smaller and the client code to interact with those libraries much simpler than with push libraries even for more complex documents e Pull clients can read multiple documents at one time with a single thread e A StAX pull parser can filter XML documents such that ele
58. requirements Note To synopsize StAX provides a standard bidirectional pull parser interface for streaming XML processing offering a simpler programming model than SAX and more efficient memory management than DOM StAX enables developers to parse and modify XML streams as events and to extend XML information models to allow application specific additions More detailed comparisons of StAX with several alternative APIs are provided below in Comparing StAX to Other JAXP APIs Why StAX The StAX project was spearheaded by BEA with support from Sun Microsys tems and the JSR 173 specification passed the Java Community Process final approval ballot in March 2004 http jcp org en jsr detai1l id 173 The primary goal of the StAX API is to give parsing control to the programmer 77 78 STREAMING API FOR XML by exposing a simple iterator based API This allows the programmer to ask for the next event pull the event and allows state to be stored in procedural fash ion StAX was created to address limitations in the two most prevalent parsing APIs SAX and DOM Steaming Versus DOM Generally speaking there are two programming models for working with XML infosets document streaming and the document object model DOM The DOM model involves creating in memory objects representing an entire document tree and the complete infoset state for an XML document Once in memory DOM trees can be navigated freely and parsed ar
59. resolved Alternatively if you do not want to report the entity as an event replacement text can be substituted and reported as Characters Processin ginstruc tion Reports the target and data for an underlying processing instruction Comment Returns the text of a comment EndDocument Reports the end of a set of XML events DTD Reports as java lang String information about the DTD if any associated with the stream and provides a method for returning custom objects found in the DTD Attribute Attributes are generally reported as part of a StartE ement event However there are times when it is desirable to return an attribute as a standalone Attribute event for example when a namespace is returned as the result of an XQuery or XPath expression Namespace As with attributes namespaces are usually reported as part of a StartE ement but there are times when it is desirable to report a namespace as a discrete Namespace event Note that the DTD EntityDeclaration EntityReference NotationDeclara tion and ProcessingInstruction events are only created if the document being processed contains a DTD ITERATOR API Sample Event Mapping 85 As an example of how the event iterator API maps an XML stream consider the following XML document lt xml version 1 0 gt lt BookCatalogue xmlIns http www publishing org gt lt Book gt lt Title gt Yogasana Vijnana the Science of
60. setState String value java math BigDecimal getZipQ void setZip java math BigDecimal value String getCountry void setCountry String value String getCityQ void setCity String value String getStreet void setStreet String value String getName void setName String value Basic Examples This section describes the Basic examples Unmarshal Read Modify Marshal Unmarshal Validate that demonstrate how to Unmarshal an XML document into a Java content tree and access the data contained within it e Modify a Java content tree e Use the ObjectFactory class to create a Java content tree from scratch and then marshal it to XML data e Perform validation during unmarshalling e Validate a Java content tree at runtime Unmarshal Read Example The purpose of the Unmarshal Read example is to demonstrate how to unmar shal an XML document into a Java content tree and access the data contained within it 1 The lt INSTALL gt examples jaxb unmarshal read Main java class declares imports for four standard Java classes plus three JAXB binding framework classes and the primer po package import java io FileInputStream import java io IOException import java util Iterator import java util List import javax xml bind JAXBContext import javax xml bind JAXBException 30 USING JAXB import javax xml bind Unmarshaller import primer po A JAXBContext instance is created for handling classes generated
61. singletonList ref Next we create the optional KeyInfo object which contains information that enables the recipient to find the key needed to validate the signature In this example we add a KeyValue object containing the public key To create KeyInfo and its various subtypes we use a KeyInfoFactory object which can be obtained by invoking the getKeyInfoFactory method of the XMLSignature Factory as follows KeyInfoFactory kif fac getKeyInfoFactoryQ We then use the KeyInfoFactory to create the KeyValue object and add it to a KeyInfo object KeyValue kv kif newKeyValue kp getPublicQ KeyInfo ki kif newKeyInfo Collections singletonList kv Finally we create the XMLSignature object passing as parameters the Signed Info and KeyInfo objects that we created earlier XMLSignature signature fac newXMLSignature si ki 229 230 JAVA XML DIGITAL SIGNATURE API Notice that we haven t actually generated the signature yet we ll do that in the next step Generating the XML Signature Now we are ready to generate the signature which we do by invoking the sign method on the XMLSignature object and pass it the signing context as follows Signature sign dsc The resulting document now contains a signature which has been inserted as the last child element of the root element Printing or Displaying the Resulting Doc ument You can use the following code to print the resulting signed document to a file or
62. standard output OutputStream os if args length gt 1 os new FileOutputStream args 1 else os System out TransformerFactory tf TransformerFactory newlInstance Transformer trans tf newTransformer trans transform new DOMSource doc new StreamResult os 8 Sec unng Web Services Tue security model used for web services is based on specifications and rec ommendations of various standards organizations see Web Services Security Initiatives and Organizations page 236 The challenge behind the security model for Java EE based web services is to understand and assess the risk involved in securing a web based service today and at the same time track emerging standards and understand how they will be deployed to offset the risk in the future This chapter addresses using message security to address the characteristics of a web service that make its security needs different from those of other Java EE applications This chapter assumes that you are familiar with the web services technologies being discussed or that you have read the following chapters in this tutorial that discuss these technologies e Chapter 1 Building Web Services with JAX WS e Chapter 3 Using JAXB e Chapter 6 Java API for XML Registries e Chapter 5 SOAP with Attachments API for Java 231 232 SECURING WEB SERVICES Securing Web Service Endpoints Web services can be deployed as EJB en
63. things that you can do with the iterator API that you cannot do with cursor API Objects created from the XMLEvent subclasses are immutable and can be used in arrays lists and maps and can be passed through your applications even after the parser has moved on to subsequent events You can create subtypes of XMLEvent that are either completely new infor mation items or extensions of existing items but with additional methods You can add and remove events from an XML event stream in much sim pler ways than with the cursor API Similarly keep some general recommendations in mind when making your choice If you are programming for a particularly memory constrained environ ment like J2ME you can make smaller more efficient code with the cur sor API If performance is your highest priority for example when creating low level libraries or infrastructure the cursor API is more efficient If you want to create XML processing pipelines use the iterator API If you want to modify the event stream use the iterator API If you want to your application to be able to handle pluggable processing of the event stream use the iterator API In general if you do not have a strong preference one way or the other using the iterator API is recommended because it is more flexible and extensible thereby future proofing your applications USING STAX Using StAX In general StAX programmers create XML stream readers writers
64. third step of a lookup operation when an application asks for the factory instance See the javadoc for the XMLInputFactory newIn stance method for more information about the lookup mechanism However there may be scenarios when an application would like to know about the factory implementation class name and set the property explicitly These sce narios could include cases where there are multiple JSR 173 implementations in the classpath and the application wants to choose one perhaps one that has supe rior performance contains a crucial bug fix or suchlike If an application sets the SystemProperty it is the first step in a lookup opera tion and so obtaining the factory instance would be fast compared to other options for example javax xml stream XMLInputFactory gt com sun xml stream ZephyrParserFactory javax xml stream XMLOutputFactory gt com sun xm stream ZephyrwriterFactor javax xml stream XMLEventFactory gt com sun xml stream events ZephyrEventFactory SAMPLE CODE Sample Code This section steps through the sample StAX code included in the J2EE 1 4 Tuto rial bundle All sample directories used in this section are located off the lt jav aee tutorial home gt examples stax directory The topics covered in this section are as follows Sample Code Organization page 99 Configuring Your Environment for Running the Samples page 100 Running the Samples page 101 Sample XML Document page 102 curs
65. this binding dec larations file will apply and the schema node at which the customizations will first take effect Subsequent binding declarations in this file will reference spe cific nodes within the schema but this first declaration should encompass the schema as a whole for example in bindings xjb lt jxb bindings schemaLocation po xsd node xs schema gt Global and Schema Binding Declarations The global schema binding declarations in bindings xjb are the same as those in po xsd for the Datatype Converter example The only difference is that because the declarations in po xsd are made inline you need to embed them in 57 58 USING JAXB lt xs appinfo gt elements which are in turn embedded in lt xs annotation gt ele ments Embedding declarations in this way is unnecessary in the external bind ings file lt jxb globalBindings fixedAttributeAsConstantProperty true collectionType java util Vector typesafeEnumBase xs NCName choiceContentProperty false typesafeEnumMemberName generateError bindingStyle elementBinding enableFailFastCheck false generateIsSetMethod false underscoreBinding asCharInWord gt lt jxb schemaBindings gt lt jxb package name primer myPo gt lt jxb javadoc gt lt CDATA lt body gt Package level documentation for generated package primer myPo lt body gt gt lt jxb javadoc gt lt jxb package gt lt jxb nameXm1Transform gt lt jxb elementName suffix Element
66. to use the StAX Stream Filter APIs In this example the filter accepts only Start Element and EndElement events and filters out the remainder of the events e readnwrite contains EventProducerConsumer java which illustrates how the StAX producer consumer mechanism can be used to simulta neously read and write XML streams e writer contains Cursorwriter java which illustrates how to use XML StreamWriter to write an XML file programatically Configuring Your Environment for Running the Samples The instructions for configuring your environment are the same as those for run ning the other J2EE Tutorial samples Specifically to configure your environ ment for running the StAX examples follow the steps below Note If you are configuring the samples to run in a Microsoft Windows environ ment use UNIX style forward slashes rather than Windows style backslashes to separate directory names when specifying paths in the steps below For exam ple if your Application Server PE installation is in c Sun AppServer specify c Sun AppServer instead 1 Set the following two properties in lt javaee tutorial home gt exam ples common build properties e javaee home to the directory in which SJSAS PE 9 0 is installed e javaee tutorial home to the directory in which the J2EE 1 4 Tutorial is installed 2 Specify the admin password used for your Application Server installation in lt javaee tutorial home gt examples common admi
67. urn uuid 7922839 f1f7 9228 c97d ce0b4594736c State urn uuid PostalAddressAttributes PostalCode urn uuid 7922839 f1Ff7 9228 c97d ce0b4594736c ZipCode urn uuid PostalAddressAttributes Country urn uuid 7922839 f1f7 9228 c97d ceQb4594736c Country After you create the connection using these properties you can create a postal address and assign it to the primary contact of the organization before you pub lish the organization String streetNumber 99 String street Imaginary Ave Suite 33 String city Imaginary City String state NY String country USA String postalCode 00000 String type PostalAddress postAddr blcm createPostalAddress streetNumber street city state country postalCode type Collection lt PostalAddress gt postalAddresses new ArrayList lt PostalAddress gt postalAddresses add postAddr primaryContact setPostalAddresses postalAddresses RUNNING THE CLIENT EXAMPLES 199 If the postal address scheme and semantic equivalences for the query are the same as those specified for the publication a JAXR query can then retrieve the postal address using PostalAddress methods To retrieve postal addresses when you do not know what postal address scheme was used to publish them you can retrieve them as a collection of Slot objects The JAXRQueryPostal java sam ple program shows how to do this In general you can create a user defined postal address t
68. xmIns ns http gizmos com NSURI SOAP ENV actor http gizmos com orders gt lt ns shippingDesk xmIns ns http gizmos com NSURI SOAP ENV actor http gizmos com shipping gt lt ns confirmationDesk xmIns ns http gizmos com NSURI SOAP ENV actor http gizmos com confirmations SOAP ENV mustUnderstand 1 gt lt ns billingDesk xmlns ns http gizmos com NSURI SOAP ENV actor http gizmos com billing gt lt SOAP ENV Header gt lt SOAP ENV Body gt lt SOAP ENV Envelope gt Header name is http gizmos com NSURI orderDesk Actor is http gizmos com orders mustUnderstand is false Header name is http gizmos com NSURI shi ppingDesk Actor is http gizmos com shipping mustUnderstand is false Header name is http gizmos com NSURI confirmationDesk Actor is http gizmos com confirmations mustUnderstand is true Header name is http gizmos com NSURI bi11ingDesk Actor is http gizmos com billing mustUnderstand is false When you run HeaderExample to generate a SOAP 1 2 message you will see output similar to the following Request Message lt env Envelope xmlns env http www w3 0rg 2003 05 soap envelope gt lt env Header gt lt ns orderDesk xmlns ns http gizmos com NSURI env role http gizmos com orders gt lt ns shippingDesk xmlns ns http gizmos com NSURI env role http gizmos com shipping gt 162 SOAP WITH ATTACHMENTS API FOR JAVA lt ns confirmatio
69. xsd positiveInteger gt lt xsd maxExclusive value 100 gt lt xsd restriction gt lt xsd simpleType gt lt xsd element gt lt xsd element name USPrice type xsd decimal gt lt xsd element ref comment minOccurs 0 gt lt xsd element name ShipDate type xsd date minOccurs 0 gt lt xsd sequence gt lt xsd attribute name partNum type SKU use required gt lt xsd complexType gt Items ItemType lt xsd element gt lt xsd sequence gt lt xsd complexType gt lt Stock Keeping Unit a code for identifying products lt xsd simpleType name SKU gt lt xsd restriction base xsd string gt lt xsd pattern value d 3 A Z 2 gt lt xsd restriction gt lt xsd simpleType gt lt xsd schema gt 22 USING JAXB Schema Denved J AXB Classes The code for the individual classes generated by the JAXB binding compiler for the Basic examples is listed below followed by brief explanations of its functions The classes listed here are Comment java Items java ObjectFactory java PurchaseOrder java PurchaseOrderType java USAddress java Commentjava In Comment java The Comment java class is part of the primer po package Comment is a public interface that extends javax xml bind Element Content in instantiations of this class bind to the XML schema element named comment The getValue and setValue methods are used to get and set strings repre senting X
70. 181 submitting data with JAXR 186 UDDI 172 registry objects 173 retrieving with JAXR 205 RegistryObject interface 173 RegistryService interface 173 180 request response messaging 122 resource adapter JAXR 175 creating resources 208 resource adapters JAXR 208 resources JAXR 208 S SAAJ 117 examples 151 messages 118 overview 118 specification 117 tutorial 123 sample applications XWS Security simple 248 258 INDEX sample programs XWS Security 248 saveConcepts method 190 saveOrganizations method 190 SAX 77 security credentials for XML registries 186 end to end 234 security tokens 247 service bindings adding to an organization with JAXR 189 finding with JAXR 185 services adding to an organization with JAXR 189 finding with JAXR 185 setContent method 135 137 setPostalAddresses method 198 signing SOAP messages 247 SOAP xv xvi xxiv 117 body 129 adding content 127 Content Type header 137 envelope 129 headers adding content 133 Content Id 137 Content Location 137 Content Type 137 example 160 SOAP faults 145 detail 147 fault actor 147 fault code 146 fault string 147 retrieving information 149 SAAJ example 168 SOAP messages encrypting 247 signing 247 verifying 247 SOAPBody interface 119 129 SOAPBodyElement interface 127 129 158 SOAPConnection class 122 getting objects 131 SOAPElement interface 128 158 SOAPEnvelope interface 119 127 129 SOAPFactory class 127 SOAPFault interface 14
71. 40 USING JAXB lt jxb bindings node xs complexType name USAddress gt In such cases the customization is applied to the node by the binding compiler as if the declaration was embedded inline in the node s lt xs appinfo gt element To summarize these rules the external binding element lt jxb bindings gt is only recognized for processing by a JAXB binding compiler in three cases e When its parent is an lt xs appinfo gt element e When it is an ancestor of another lt jxb bindings gt element e When it is root element of a document an XML document that has a lt jxb bindings gt element as its root is referred to as an external binding declaration file Scope Inheritance and Precedence Default JAXB bindings can be customized or overridden at four different levels or scopes as described in Table 3 7 Figure 3 1 illustrates the inheritance and precedence of customization declara tions Specifically declarations towards the top of the pyramid inherit and super sede declarations below them For example Component declarations inherit from and supersede Definition declarations Definition declarations inherit and supersede Schema declarations and Schema declarations inherit and supersede Global declarations CUSTOMIZATION OVERVIEW Global Scope Figure 3 1 Customization Scope Inheritance and Precedence Customization Syntax The syntax for the four types of JAXB binding declarations as well as the synt
72. 5yhMjSc BrIVC58w3ydbkK Ri40KbaRZ1 YeRA lt Y gt lt DSAKeyValue gt lt KeyValue gt lt KeyInfo gt XML DIGITAL SIGNATURE API EXAMPLES 221 This KeyInfo element contains a KeyValue element which in turn contains a DSAKeyValue element consisting of the public key needed to validate the signa ture KeyInfo can contain various content such as X 509 certificates and PGP key identifiers See the KeyInfo section of the XML Signature Recommenda tion for more information on the different KeyInfo types XML Digital Signature API Examples The following sections describe two examples that show how to use the XML Digital Signature API e Validate example e Signing example To run the sample applications using the supplied Ant build xml files issue the following commands after you installed Java WSDP For Solaris Linux 1 export JWSDP_HOME lt your Java WSDP installation directory gt 2 export ANT_HOME JWSDP_HOME apache ant 3 export PATH ANT_HOME bin PATH 4 cd JWSDP_HOME xmldsig samples lt samp1e name gt For Windows 2000 XP set JWSDP_HOME lt your Java WSDP installation directory gt set ANT_HOME JWSDP_HOME apache ant set PATH ANT_HOME bin PATH gt gt gt gt cd JWSDP_HOME xml1dsig samples lt samp1e name gt AUN validate Example You can find the code shown in this section in the Validate java file in the lt JWSDP_HOME gt xm1dsig samples validate directory The file on which it operates
73. 6 creating and populating ob jects 147 detail element 147 fault actor element 147 fault code element 146 fault string element 147 SOAPHeader interface 119 133 SOAPHeaderElement interface 127 133 SOAPMessage Class 119 125 126 SOAPPart class 119 122 128 adding content 134 specification concepts publishing with JAXR 190 204 removing with JAXR 205 T taxonomies finding with JAXR 188 ISO 3166 181 NAICS 181 202 UNSPSC 181 user defined 194 using to find organizations 183 tokens security 247 typographical conventions xiii U UDDI accessing registries with SAAJ 153 registries 172 Universal Standard Products and Services Classification UNSPSC 181 UNSPSC 181 Vv verifying SOAP messages 247 W W3C xvi xxiv web services examples xvi WSDL xvi xxiv publishing concepts for with JAXR 204 publishing with JAXR 190 removing concepts for with JAXR 205 using to find organizations 183 205 wsgen tool xvii INDEX 259 X XML xv documents and SAAJ 118 elements in SOAP messages 118 registries establishing security cre dentials 186 XWS Security framework 247 sample programs 248
74. API is really two distinct API sets a cursor API and an iterator API These two API sets explained in greater detail later in this chapter but their main features are briefly described below Cursor API As the name implies the StAX cursor API represents a cursor with which you can walk an XML document from beginning to end This cursor can point to one thing at a time and always moves forward never backward usually one infoset element at a time 82 STREAMING API FOR XML The two main cursor interfaces are XMLStreamReader and XMLStreamwriter XMLStreamReader includes accessor methods for all possible information retrievable from the XML Information model including document encoding element names attributes namespaces text nodes start tags comments pro cessing instructions document boundaries and so forth for example public interface XMLStreamReader public int nextQ throws XMLStreamException public boolean hasNext throws XMLStreamException public String getTextQ public String getLocalName public String getNamespaceURI other methods not shown You can call methods on XMLStreamReader such as getText and getName to get data at the current cursor location XMLStreamwriter provides methods that correspond to StartElement and EndElement event types for example public interface XMLStreamwWriter public void writeStartElement String localName throws XMLStreamException public void writeEnd
75. BContext jc JAXBContext newInstance primer po 3 An Unmarshal ler instance is created and po xm1 is unmarshalled Unmarshaller u jc createUnmarshallerQ PurchaseOrder po PurchaseOrder u unmarshal new FileInputStream po xml 4 set methods are used to modify information in the address branch of the content tree USAddress address po getBillToQ address setName John Bob address setStreet 242 Main Street address setCity Beverly Hills address setState CA address setZip new BigDecimal 90210 5 A Marshal ler instance is created and the updated XML content is mar shalled to system out The setProperty API is used to specify output encoding in this case formatted human readable XML format Marshaller m jc createMarshaller m setProperty Marshal ler JAXB_FORMATTED_OUTPUT Boolean TRUE m marshal po System out Sample Output Running java Main for this example produces the following output lt xml version 1 0 encoding UTF 8 standalone yes gt lt purchaseOrder orderDate 1999 10 20 05 00 gt lt shiplo country US gt lt name gt Alice Smith lt name gt lt street gt 123 Maple Street lt street gt UNMARSHAL VALIDATE EXAMPLE lt city gt Cambridge lt city gt lt state gt MA lt state gt lt Zip gt 12345 lt zip gt lt shipTo gt lt bil1To country US gt lt name gt John Bob lt name gt lt street gt 242 Main Street lt street gt
76. BigInteger getQuantityQ void setQuantity java math BigInteger value ObjectFactory java In ObjectFactory java below e The ObjectFactory class is part of the primer po package e ObjectFactory provides factory methods for instantiating Java interfaces representing XML content in the Java content tree e Method names are generated by concatenating e The string constant create e Ifthe Java content interface is nested within another interface then the concatenation of all outer Java class names e The name of the Java content interface e JAXB implementation specific code was removed in this example to make it easier to read For example in this case for the Java interface primer po Items ItemType ObjectFactory creates the method createItemsItemType The ObjectFactory java code looks like this package primer po public class ObjectFactory extends com sun xml bind DefaultJAXBContextImp1 Create a new ObjectFactory that can be used to create new instances of schema derived classes for package primer po my public ObjectFactory super new primer po ObjectFactory GrammarInfolImp Create an instance of the specified Java content interface public Object newInstance Class javaContentInterface SCHEMA DERIVED JAXB CLASSES 25 throws javax xml bind JAXBException es Get the specified property This method can only be used to get provider specific properties A
77. DatatypeCon verter java which illustrates print and parse methods in the lt javaType gt cus tomization for handling custom datatype conversions To summarize this example 1 po xsd is an XML schema containing inline binding customizations 2 MyDatatypeConverter java is a Java class file that implements print and parse methods specified by lt javaType gt customizations in po xsd 50 USING JAXB 3 Main java is the primary class file in the Customize Inline example which uses the schema derived classes generated by the JAXB compiler Key customizations in this sample and the custom MyDatatypeConverter java class are described in more detail below Customized Schema The customized schema used in the Customize Inline example is in the file lt JAVA_HOME gt jaxb samples inline customize po xsd The customizations are in the lt xsd annotation gt tags Global Binding Declarations The code below shows the globalBindings declarations in po xsd lt jxb globalBindings fixedAttributeAsConstantProperty true collectionType java util Vector typesafeEnumBase xsd NCName choiceContentProperty false typesafeEnumMemberName generateError bindingStyle elementBinding enableFailFastCheck false generateIsSetMethod false underscoreBinding asCharInWord gt In this example all values are set to the defaults except for col lectionType e Setting collectionType to java util Vector specifies that all lists in
78. ENTATION IS PROVIDED AS IS AND ALL EXPRESS OR IMPLIED CONDITIONS REPRESENTATIONS AND WARRANTIES INCLUDING ANY IMPLIED WARRANTY OF MER CHANTABILITY FITNESS FOR A PARTICULAR PURPOSE OR NON INFRINGEMENT ARE DISCLAIMED EXCEPT TO THE EXTENT THAT SUCH DISCLAIMERS ARE HELD TO BE LEGALLY INVALID Copyright 2006 Sun Microsystems Inc 4150 Network Circle Santa Clara California 95054 Etats Unis Tous droits r serv s Droits du gouvernement am ricain utlisateurs gouvernmentaux logiciel commercial Les utilisateurs gouvernmentaux sont soumis au contrat de licence standard de Sun Microsystems Inc ainsi qu aux dis positions en vigueur de la FAR Federal Acquisition Regulations et des suppl ments celles ci Cette distribution peut comprendre des composants d velopp s pardes tierces parties Sun Sun Microsystems le logo Sun Java JavaServer Pages Enterprise JavaBeans Java Naming and Directory Interface EJB JSP J2EE J2SE et le logo Java Coffee Cup sont des marques de fabrique ou des marques d pos es de Sun Microsystems Inc aux Etats Unis et dans d autres pays A moins qu autrement autoris le code de logiciel en tous les mat riaux techniques dans le pr sent arti cles y compris FAQs chantillons est fourni sous ce permis Les produits qui font l objet de ce manuel d entretien et les informations qu il contient sont r gis par la l gislation am ricaine en mati re de contr le des exportations et
79. Element throws XMLStreamException public void writeCharacters String text throws XMLStreamException other methods not shown The cursor API mirrors SAX in many ways For example methods are available for directly accessing string and character information and integer indexes can be used to access attribute and namespace information As with SAX the cursor API methods return XML information as strings which minimizes object alloca tion requirements Iterator API The StAX iterator API represents an XML document stream as a set of discrete event objects These events are pulled by the application and provided by the parser in the order in which they are read in the source XML document The base iterator interface is called XMLEvent and there are subinterfaces for each event type listed in Table 4 2 below The primary parser interface for read ITERATOR API 83 ing iterator events is XMLEventReader and the primary interface for writing iter ator events is XMLEventWriter The XMLEventReader interface contains five methods the most important of which is nextEvent which returns the next event in an XML stream XMLEventReader implements java util Iterator which means that returns from XMLEventReader can be cached or passed into routines that can work with the standard Java Iterator for example public interface XMLEventReader extends Iterator public XMLEvent nextEvent throws XMLStreamException public bool
80. J AXRQueryByNAIC SC lassifc ation Example After you run the JAXRPublish program you can also run the JAXRQueryByNA IcSClassification example which looks for organizations that use the All Other Specialty Food Stores classification the same one used for the organiza tion created by JAXRPublish To do so use the asant target run query naics asant run query naics Running the J AXRDelete Example To run the JAXRDelete program specify the key string displayed by the JAXR Publish program as input to the run delete target asant Dkey string keyString run delete RUNNING THE EXAMPLES 203 Publishing a Classification Scheme To publish organizations with postal addresses you must first publish a classifi cation scheme for the postal address To run the JAXRSaveClassificationScheme program use the target run save scheme asant run save scheme The program returns a UUID string which you will use in the next section Running the Postal Address Examples Before you run the postal address examples perform these steps 1 Open the file src postalconcepts xm1 in an editor 2 Wherever you see the string uuid from save replace it with the UUID string returned by the run save scheme target including the uuid pre fix For a given registry you only need to publish the classification scheme and edit postalconcepts xml once After you perform those steps you can run the JAXRPublishPostal and JAXRQueryPostal programs multi
81. JAXB binding dec larations file specifies the schema name and the root schema node lt jxb bindings schemaLocation po xsd node xs schema gt A subsequent schemaLocation node declaration say for a simpleType element named Zi pCodeType in the above schema would take the form lt jxb bindings node xs simpleType name ZipCodeType gt Binding Customization File Format Binding customization files should be straight ASCII text The name or exten sion does not matter although a typical extension used in this chapter is xjb Passing Customization Files to the J AXB Binding Compiler Customization files containing binding declarations are passed to the JAXB Binding compiler xjc using the following syntax xjc b lt file gt lt schema gt where lt file gt is the name of binding customization file and lt schema gt is the name of the schema s you want to pass to the binding compiler CUSTOMIZATION OVERVIEW You can have a single binding file that contains customizations for multiple sche mas or you can break the customizations into multiple bindings files for exam ple xjc schemal xsd schema2 xsd schema3 xsd b bindings123 xjb xjc schemal xsd schema2 xsd schema3 xsd b bindings1l xjb b bindings2 xjb b bindings3 xjb Note that the ordering of schema files and binding files on the command line does not matter although each binding customization file must be preceded by its own b switch on the
82. L Digital Signature API are related In this release of the Java WSDP XWS Secu rity is based on non standard XML Digital Signature APIs XML Digital Signature API is an API that should be used by Java applications and middleware that need to create and or process XML Signatures It can be used by Web Services Security the goal for a future release and by non Web Services technologies for example signing documents stored or transferred in XML Both JSR 105 and JSR 106 XML Digital Encryption APIs are core XML security components See http ww jcp org en jsr detai1 id 106 for more information about JSR 106 XWS Security does not currently use the XML Digital Signature API or XML Digital Encryption APIs XWS Security uses the Apache libraries for XML DSig and XML Enc The goal of XWS Security is to move toward using these APIs in future releases XML SECURITY STACK 215 XML Sec unty Stack Figure 7 1 shows how XML Digital Signature API JSR 105 interacts with security components today and how it will interact with other security compo nents including XML Digital Encryption API JSR 106 in future releases JSR 105 JSR 105 JSR 105 JSR 105 Provider JSR 106 Provider JSR 105 Provider Pluggable Pluggable Apache XML Security Security W Security E Provider Provider y Java Cryptography Java Cryptography Architecture Acchitecture JCA Provider JCA Provider Sun JCA Pluggable JCA Provider Provider Figure 7 1 Java WSDP Sec
83. LL gt javaeetutorial5 exam ples jaxws helloservice and the client is in lt INSTALL gt javaeetutorial5 examples jaxws simpleclient Figure 1 1 illustrates how JAX WS technology manages communication between a web service and client CREATING A SIMPLE WEB SERVICE AND CLIENT WITH JAX WS pru ___ HelloClient Program HelloService Stubs Ties JAX RPC SOAP JAX RPC Runtime Runtime Message Figure 1 1 Communication Between a JAX WS Web Service and a Client The starting point for developing a JAX WS web service is a Java class anno tated with the javax jws WebService annotation The WebService annotation defines the class as a web service endpoint A service endpoint interface SEI is a Java interface that declares the methods that a client can invoke on the service An SEI is not required when building a JAX WS endpoint The web service implementation class implicitly defines a SEI You may specify an explicit SEI by adding the endpointInterface element to the WebService annotation in the implementation class You must then provide a SEI that defines the public methods made available in the endpoint implementa tion class You use the endpoint implementation class and the wsgen tool to generate the web service artifacts and the stubs that connect a web service client to the JAX WS runtime For reference documentation on wsgen see the Application Server man pages at http docs sun com db doc 817 6092 Togethe
84. ML 1 0 http www w3 org TR REC xml XML Information Set http www w3 org TR xml infoset JAXB specification http java sun com xm1 jaxb JAX RPC specification http java sun com xml jaxrpc W3C Recommendation Document Object Model http www w3 org DOM SAX Simple API for XML http www saxproject org DOM Document Object Model http www w3 org TR 2002 WD DOM Level 3 Core 20020409 core htm1 ID B63ED1A3 W3C Recommendation Namespaces in XML http www w3 org TR REC xml names For some useful articles about working with StAX see Jeff Ryan Does StAX Belong in Your XML Toolbox http www developer com xml article php 3397691 Elliotte Rusty Harold An Introduction to StAX http www xml com pub a 2003 09 17 stax html More efficient XML parsing with the Streaming API for XML http www 106 ibm com developerworks xml library x tipstx 5 SOAP with Attachments API for Java Soar with Attachments API for Java SAAJ is used mainly for the SOAP messaging that goes on behind the scenes in JAX WS handlers and JAXR imple mentations Secondarily it is an API that developers can use when they choose to write SOAP messaging applications directly rather than use JAX WS The SAAJ API allows you to do XML messaging from the Java platform By simply making method calls using the SAAJ API you can read and write SOAP based XML messages and you can optionally s
85. ML comment elements in the Java content tree The Comment java code looks like this package primer po public interface Comment extends javax xml bind Element String getValue void setValue String value SCHEMA DERIVED JAXB CLASSES 23 Items java In Items java below e The Items java class is part of the primer po package e The class provides public interfaces for Items and ItemType e Content in instantiations of this class bind to the XML ComplexTypes Items and its child element ItemType e Item provides the getItem method e ItemType provides methods for e getPartNum e setPartNum String value e getComment e setComment java lang String value e getUSPriceQ e setUSPrice java math BigDecimal value e getProductName e setProductName String value e getShipDateQ e setShipDate java util Calendar value e getQuantityQ e setQuantity java math BigInteger value The Items java code looks like this package primer po public interface Items java util List getItemQ public interface ItemType String getPartNum void setPartNum String value java lang String getComment void setComment java lang String value java math BigDecimal getUSPrice void setUSPrice java math BigDecimal value String getProductName void setProductName String value java util Calendar getShipDateQ void setShipDate java util Calendar value 24 USING JAXB java math
86. MMENT return COMMENT case XMLEvent START_DOCUMENT return START_DOCUMENT case XMLEvent END_DOCUMENT return END_DOCUMENT case XMLEvent ENTITY_REFERENCE return ENTITY_REFERENCE case XMLEvent ATTRIBUTE return ATTRIBUTE case XMLEvent DTD return DTD case XMLEvent CDATA return CDATA case XMLEvent SPACE CURSOR2EVENT SAMPLE CURSORA PPROACHE VENTOBJECT JAVA return SPACE return UNKNOWN_EVENT_TYPE eventType Running the Sample When you run the CursorParse sample the class is compiled and the XML stream is parsed and returned to STDOUT cursor2event Sample CursorpproachEventObjectjava Located in the lt javaee tutorial home gt examples stax cursor2event directory CursorApproachEventObject java demonstrates how to get infor mation returned by an XMLEvent object even when using the cursor API The idea here is that the cursor API s XMLStreamReader returns integer con stants corresponding to particular events where as the event iterator API s XMLEventReader returns immutable and persistent event objects XMLStream Reader is more efficient but XMLEventReader is easier to use as all the informa tion related to a particular event is encapsulated in a returned XMLEvent object However the disadvantage of event approach is the extra overhead of creating objects for every event which consumes both time and memory With this mind XMLEventAl locator can be used to get even
87. One or more Reference elements identify the data that is digested Each Refer ence element identifies the data via a URI In this example the value of the URI is the empty String which indicates the root of the document The optional Transforms element contains a list of one or more Transform elements each of which describes a transformation algorithm used to transform the data before it is digested In this example there is one Transform element for the enveloped transform algorithm The enveloped transform is required for enveloped signa tures so that the signature element itself is removed before calculating the signa ture value The required DigestMethod element defines the algorithm used to digest the data in this case SHA1 Finally the required DigestValue element contains the actual base64 encoded digested value The required SignatureValue element contains the base64 encoded signature value of the signature over the SignedInfo element The optional KeyInfo element contains information about the key that is needed to validate the signature lt KeyInfo gt lt KeyValue gt lt DSAKeyValue gt lt P gt KaCzo4Syrom78z3EQ5SbbB4sF7ey80etKI1864WF64B81uRpH5t9jQTxe EuQ ImbzRMqzVDZkVG9xD7nN1kuFw lt P gt lt Q gt 1i17dzDacuo67Jg7mtqEm2TRUOMU lt Q gt lt G gt Z4Rxsnqc9E7pGknFFH2xqaryRPBaQ 1khpMdLRQnG541Awtx XPaF5Bpsy4pNwMOHCB 71 NU NogpsQW5Qvn 1 MpA lt G lt Y gt qVv38IqrWIGOV mZQvRVi 10HW9Zj 84nDC4j08PQaxi Lgb6d 47
88. Profile is a document that clarifies the SOAP 1 1 and WSDL 1 1 specifications in order to promote SOAP interoperability For links related to WS I see Further Information page xxiv xxiii xxiv BUILDING WEB SERVICES WITH JAX WS To support WS I Basic Profile Version 1 1 JAX WS has the following features e The JAX WS runtime supports doc literal and rpc literal encodings for ser vices static stubs dynamic proxies and DII Further Information For more information about JAX WS and related technologies refer to the fol lowing Java API for XML Web Services 2 0 specification https jax ws dev java net spec download htm JAX WS home https jax ws dev java net Simple Object Access Protocol SOAP 1 2 W3C Note http www w3 org TR SOAP Web Services Description Language WSDL 1 1 W3C Note http www w3 org TR wsdl WS I Basic Profile 1 1 http www ws 7 org 2 Binding between XML Schema and Java Classes Tue Java Architecture for XML Binding JAXB provides a fast and conve nient way to bind between XML schemas and Java representations making it easy for Java developers to incorporate XML data and processing functions in Java applications As part of this process JAXB provides methods for unmar shalling XML instance documents into Java content trees and then marshalling Java content trees back into XML instance documents JAXB also provides a way generate XML schema from Java objects This c
89. S Secu rity to secure messages WS Security is a message security mechanism that uses XML Encryption and XML Digital Signature to secure web services messages sent over SOAP The WS Security specification defines the use of various secu rity tokens including X 509 certificates SAML assertions and username pass word tokens to authenticate and encrypt SOAP web services messages The Application Server offers integrated support for the WS Security standard in its web services client and server side containers This functionality is integrated such that web services security is enforced by the containers of the Application Server on behalf of applications and such that it can be applied to protect any web service application without requiring changes to the implementation of the application The Application Server achieves this effect by providing facilities to bind SOAP layer message security providers and message protection policies to containers and to applications deployed in containers There are two ways to enable message security when using the Application Server e Configure the Application Server so that web services security will be applied to all web services applications deployed on the Application Server For more information read How Does WSS Work in the Applica tion Server page 242 e Configure application specific web services security by annotating the server specific deployment descriptor For more information read Config
90. S Security and XML Digital Signature API Are Related 214 XML Security Stack 215 Package Hierarchy 216 Service Providers 217 Introduction to XML Signatures 218 Example of an XML Signature 218 XML Digital Signature API Examples 221 validate Example 221 genenveloped Example 226 Securing Web Services 200 eee eee QOL Securing Web Service Endpoints 232 Overview of Message Security 232 Advantages of Message Security 233 Message Security Mechanisms 235 Web Services Security Initiatives and Organizations 236 W3C Specifications 236 OASIS Specifications 237 JCP Specifications 238 WS I Specifications 239 Using Message Security with Java EE 241 Using the Application Server Message Security Implementation 242 Using the Java WSDP XWSS Security Implementation 247 Further Information 251 IndeX oof tec ae eae ee ea i eee ae eee vii CONTENTS About This Tutonal Tue Java Web Services Tutorial is a guide to developing Web applications with the Java Web Services Developer Pack Java WSDP The Java WSDP is an all in one download containing key technologies to simplify building of Web services using the Java 2 Platform This tutorial requires a full installation Typi cal of the Java WSDP v2 0 with the Sun Java System Application Server Plat form Edition 9 hereafter called the Application Server Here we cover all the things you need to know to make the best use of this tutorial Who Should Use This Tutonal This tutorial i
91. Server naics xml 1s03166 xm1 and unspsc xm1 The entries in the jaxrconcepts xm1 file look like this lt PredefinedConcepts gt lt JAXRClassificationScheme id schId name schName gt lt JAXRConcept id schId conCode name conName parent parentId code conCode gt lt JAXRConcept gt lt JAXRClassi fi cati onScheme gt lt PredefinedConcepts gt The taxonomy structure is a containment based structure The element Pre definedConcepts is the root of the structure and must be present The JAXR ClassificationScheme element is the parent of the structure and the USING TAXONOMIES IN JAXR CLIENTS JAXRConcept elements are children and grandchildren A JAXRConcept element may have children but it is not required to do so In all element definitions attribute order and case are significant To add a user defined taxonomy follow these steps 1 Publish the JAXRClassificationScheme element for the taxonomy as a ClassificationScheme object in the registry that you will be accessing To publish a ClassificationScheme object you must set its name You also give the scheme a classification within a known classification scheme such as uddi org types In the following code fragment the name is the first argument of the Li feCycleManager createClassificationScheme method call InternationalString sn blcm createInternationalStringC MyScheme InternationalString sd blcm createInternationalString A Classification Schem
92. TE case XMLEvent DTD return DTD case XMLEvent CDATA return CDATA case XMLEvent SPACE return SPACE return UNKNOWN_EVENT_TYPE eventType Running the Sample When you run the EventParse sample the class is compiled and the XML stream is parsed as events and returned to STDOUT For example an instance of the Author element is returned as lt http ww publishing org Author gt Dhirendra Brahmachari lt http ww publishing org Author gt Note in this example that the event comprises an opening and closing tag both of which include the namespace The content of the element is returned as a string within the tags Similarly an instance of the Cost element is returned as lt http ww publishing org Cost currency INR gt 11 50 lt http ww publishing org Cost gt In this case the currency attribute and value are returned in the opening tag for the event See earlier in this chapter in the Iterator API and Reading XML Streams sections for a more detailed discussion of StAX event parsing FILTER SAMPLE MYSTREAMFILTER JAVA 109 fiter Sample MySteamfilterjava Located in the lt javaee tutorial home gt examples stax filter directory MyStreamFilter java demonstrates how to use the StAX stream filter API to filter out events not needed by your application In this example the parser filters out all events except StartElement and EndElement I
93. The application in this section uses two components an application client and a stateless session bean The section covers the following topics e Coding the application client MyAppClient java e Coding the PubQuery session bean e Compiling the source files e Starting the Application Server e Creating JAXR resources e Creating and packaging the application e Deploying the application e Running the application client You will find the source files for this section in the directory lt INSTALL gt javaeetutorial5 examples jaxr clientsession Path names in this section are relative to this directory The following directory contains a built version of this application lt INSTALL gt javaeetutorial5 examples jaxr provided ears CODING THE APPLICATION CLIENT MYA PPCLIENT JAVA Coding the Applic ation Client MyAppClientjava The application client class src MyAppClient java accesses the PubQuery enterprise bean s remote interface The program calls the bean s two business methods executePublish and executeQuery Coding the PubQuery Session Bean The PubQuery bean is a stateless session bean that has two business methods The bean uses remote interfaces rather than local interfaces because it is accessed from the application client The remote interface src PubQueryRemote java declares two business meth ods executePublish and executeQuery The bean class src PubQuery Bean java implements the executePublish and exe
94. Type anno tation statements override the package definition and specify the field to be of type date Property method getTrackingDuration defines the schema element to be defined as primitive type duration and not Java type String j2s xmlType Example The j2s xmlType example demonstrates the use of annotation XmlType Annotation XmlType maps a class or an enum type to a XML Schema type A class must have either a public zero arg constructor or a static zero arg factory method in order to be mapped by this annotation One of these methods is used during unmarshalling to create an instance of the class The factory method may reside within in a factory class or the existing class There is an order of presed ence as to which method is used for unmarshalling e Ifa factory class is identified in the annotation a corresponding factory method in that class must also be identified and that method will be used e Ifa factory method is identified in the annotation but no factory class is identified the factory method must reside in the current class The factory method is used even if there is a public zero arg constructor method present e Ifno factory method is identified in the annotation the class must contain a public zero arg constructor method J2S XMLTYPE EXAMPLE 75 In this example a factory class provides zero arg factory methods for several classes The XmlType annotation on class OrderContext references the fac tory class Th
95. a class that can represent additional characteristics of the built in XML Schema datatype Customization Overview This section explains some core JAXB customization concepts e Inline and External Customizations e Scope Inheritance and Precedence e Customization Syntax e Customization Namespace Prefix Inline and Extemal Customizations Customizations to the default JAXB bindings are made in the form of binding declarations passed to the JAXB binding compiler These binding declarations can be made in either of two ways e As inline annotations in a source XML schema e As declarations in an external binding customizations file For some people using inline customizations is easier because you can see your customizations in the context of the schema to which they apply Conversely using an external binding customization file enables you to customize JAXB CUSTOMIZATION OVERVIEW bindings without having to modify the source schema and enables you to easily apply customizations to several schema files at once Note You can combine the two types of customizations for example you could include a reference to an external binding customizations file in an inline annota tion but you cannot declare both an inline and external customization on the same schema element Each of these types of customization is described in more detail below Inline C ustomizations Customizations to JAXB bindings made by means of inline b
96. actions and authorization services e eXtensible Access Control Markup Language XACML The XACML specification defines a common language for expressing security policy XACML defines an extensible structure for the core schema and namespace for expressing authorization policies in XML A common policy language when implemented across an enterprise allows the enterprise to manage the enforcement of all the elements of its secu rity policy in all the components of its information systems J CP Specific ations According to the Java Community Process JCP web site the JCP holds the responsibility for the development of Java technology The JCP primarily guides the development and approval of Java technical specifications The JCP is work ing on the following specifications related to web services security The specifi cations can be viewed from the JCP web site at http www jcp org en jsr all e JSR 104 XML Trust Service APIs JSR 104 defines a standard set of APIs and a protocol for a trust service A key objective of the protocol design is to minimize the complexity of applications using XML Signature By becoming a client of the trust ser vice the application is relieved of the complexity and syntax of the under lying PKI used to establish trust relationships which may be based upon a different specification such as X 509 PKIX SPKI or PGP e JSR 105 XML Digital Signature APIs JSR 105 defines a standard set of APIs for XML d
97. ample XML content and is the file you will unmarshal into a Java content tree in each example This file is almost exactly the same in each example with minor content USING THE EXAMPLES differences to highlight different JAXB concepts Note that the Fix Col lides example uses example xm1 rather than po xm1 e Main java is the main Java class for each example e build xml is an Ant project file provided for your convenience Use Ant to generate compile and run the schema derived JAXB classes automati cally The build xm1 file varies across the examples e MyDatatypeConverter java in the inline customize example is a Java class used to provide custom datatype conversions e binding xjb in the External Customize and Fix Collides examples is an external binding declarations file that is passed to the JAXB binding com piler to customize the default JAXB bindings e example xsd in the Fix Collides example is a short schema file that con tains deliberate naming conflicts to show how to resolve such conflicts with custom JAXB bindings Using the Examples As with all applications that implement schema derived JAXB classes as described above there are two distinct phases in using JAXB 1 Generating and compiling JAXB Java classes from an XML source schema 2 Unmarshalling validating processing and marshalling XML content In the case of these examples you perform these steps by using asant with the build xm1 project file
98. and Service Bindings After a client has located an organization it can find that organization s services and the service bindings associated with those services Iterator orgIter orgs iterator while CorgIter hasNext Organization org Organization orgIter nextQ Collection services org getServices Iterator svcIter services iterator while svcIter hasNextQ Service svc Service svcIter nextQ Collection serviceBindings svc getServiceBindings Iterator sbIter serviceBindings iterator while sbIter hasNext Q ServiceBinding sb ServiceBinding sbIter nextQ 186 JAVA API FOR XML REGISTRIES Managing Registry Data If a client has authorization to do so it can submit data to a registry modify it and remove it It uses the BusinessLifeCycleManager interface to perform these tasks Registries usually allow a client to modify or remove data only if the data is being modified or removed by the same user who first submitted the data Managing registry data involves the following tasks e Getting authorization from the registry e Creating an organization e Adding classifications e Adding services and service bindings to an organization e Publishing an organization e Publishing a specification concept e Removing data from the registry Getting Authonzation from the Registry Before it can submit data the client must send its user name and password to the registry in a set of credent
99. and events by using the XMLInputFactory XMLOutputFactory and XMLEventFactory classes Configuration is done by setting properties on the factories whereby implementation specific settings can be passed to the underlying implementation using the setProperty method on the factories Similarly implementation specific settings can be queried using the getProperty factory method The XMLInputFactory XMLOutputFactory and XMLEventFactory classes are described below followed by discussions of resource allocation namespace and attribute management error handling and then finally reading and writing streams using the cursor and iterator APIs StAX Factory Classes XMUnputFactory The XMLInputFactory class lets you configure implementation instances of XML stream reader processors created by the factory New instances of the abstract class XMLInputFactory are created by calling the newInstance method on the class The static method XMLInputFactory newInstanceQ is then used to create a new factory instance Deriving from JAXP the XMLInputFactory newInstance method deter mines the specific XMLInputFactory implementation class to load by using the following lookup procedure 1 Use the javax xml stream XMLInputFactory system property 2 Use the lib xm1 stream properties file in the JRE directory 3 Use the Services API if available to determine the classname by looking in the META INF services javax xml stream XMLInputFactory files
100. art for the text attachment AttachmentPart attachmentl message createAttachmentPart ATTACHMENTS JAVA 167 After it reads input from a file into a string named stringContent it sets the content of the attachment to the value of the string and the type to text plain and also sets a content ID attachmentl setContent stringContent text plain attachment1 setContentIdC attached_text It then adds the attachment to the message message addAttachmentPart attachment1 The example uses a javax activation DataHandler object to hold a reference to the graphic that constitutes the second attachment It creates this attachment using the form of the createAttachmentPart method that takes a DataHandler argument Create attachment part for image URL url new URLC file xml pic jpg DataHandler dataHandler new DataHandler url AttachmentPart attachment2 message createAttachmentPart dataHand ler attachment2 setContentIdC attached_image message addAttachmentPart attachment2 The example then retrieves the attachments from the message It displays the contentId and contentType attributes of each attachment and the contents of the text attachment Running Attachments To run Attachments you use the file build xml that is in the directory lt INSTALL gt javaeetutorial5 examples saaj attachments To run Attachments use the following command asant run Dfile path_name Specify any text file as t
101. asant create resource Packaging the Application The build xml file in the clientsession directory defines Ant targets that package the clientsession application To package the application use the fol lowing command asant pack ear The pack ear target depends on the pack client and pack ejb targets which in turn depend on the build target The pack client target creates a JAR file that contains the client class file a manifest file and the PubQueryBeanExample properties file The pack ejb target packages the session bean It creates a JAR file that con tains the bean class files a manifest file and the PubQueryBeanExamp1e prop erties file The pack ear target packages the two JAR files along with an applica tion xm1 file It creates a file named clientsession ear in the clientses sion directory 210 JAVA API FOR XML REGISTRIES Deploying the Application The build xml file in the clientsession directory defines an Ant target that deploys the clientsession ear file and returns a client JAR file Use the fol lowing command asant deploy ear This command deploys the application and returns a JAR file named client sessionClient jar in the clientsession directory Running the Application Client To run the client use the following command appclient client clientsessionClient jar The program output in the terminal window looks like this To view the bean output check lt install_dir gt domains domain1 log
102. ation Server Using XWSS is discussed in Using the Java WSDP XWSS Security Implementation page 247 Because neither of these options for message security are part of the Java EE platform this document would not normally discuss using either of these options to secure messages However as there are currently no Java EE APIs that per form this function and message security is a very important component of web MESSAGE SECURITY MECHANISMS 235 services security this chapter presents a brief introduction to using both the WSS and XWSS functionality that is incorporated into the Sun Java System Applica tion Server This chapter includes the following topics e Message Security Mechanisms page 235 e Web Services Security Initiatives and Organizations page 236 e Using Message Security with Java EE page 241 Message Secunty Mechanisms Encryption is the transformation of data into a form that is as close to impossible as possible to read without the appropriate knowledge which is contained in a key Its purpose is to ensure privacy by keeping information hidden from anyone for whom it is not intended even those who have access to the encrypted data Decryption is the reverse of encryption it is the transformation of encrypted data back into an intelligible form Encryption and decryption generally require the use of some secret information referred to as a key For some encryption mechanisms the same key is used for both encrypt
103. ature element has been inserted inside the content that it is signing thereby making it an enveloped signature The required SignedInfo element contains the information that is actually signed lt SignedInfo gt lt CanonicalizationMethod Algorithm http www w3 org TR 2001 REC xml c14n 20010315 WithComments gt lt SignatureMethod Algorithm http www w3 org 2000 09 xmldsig dsa shal gt lt Reference URI gt lt Transforms gt lt Transform Algorithm http www w3 org 2000 09 xmldsig enveloped signature gt lt Transforms gt lt DigestMethod Algorithm http www w3 org 2000 09 xmldsig shal gt lt DigestValue gt uooqbWYa5VCqcJCbuymBKqm17vY lt DigestValue gt lt Reference gt lt SignedInfo gt The required CanonicalizationMethod element defines the algorithm used to canonicalize the SignedInfo element before it is signed or validated Canonical ization is the process of converting XML content to a canonical form to take 220 JAVA XML DIGITAL SIGNATURE API into account changes that can invalidate a signature over that data Canonicaliza tion is necessary due to the nature of XML and the way it is parsed by different processors and intermediaries which can change the data such that the signature is no longer valid but the signed data is still logically equivalent The required SignatureMethod element defines the digital signature algorithm used to generate the signature in this case DSA with SHA 1
104. ava demonstrates how to use the StAX cursor API to write an XML stream Creating the Output Factory The first step is to create an instance of XMLOutputFactory XMLOutputFactory xof XMLOutputFactory newInstance Creating a Steam Whiter The next step is to create an instance of XMLStreamWriter XMLStreamWriter xtw null Witting the Steam The final step is to write the XML stream Note that the stream is flushed and closed after the final EndDocument is written xtw xof createxXMLStreamWriter new FileWriter fileName xtw writeComment all elements here are explicitly in the HTML namespace xtw writeStartDocument utf 8 1 0 xtw setPrefix html http www w3 org TR REC htm140 xtw writeStartElementC http ww w3 org TR REC htm140 htm1 xtw writeNamespace html http www w3 org TR REC htm1 40 xtw writeStartElementC http ww w3 org TR REC htm140 head xtw writeStartElementC http ww w3 org TR REC htm140 title xtw writeCharacters C Frobnostication Xtw writeEndElement xtw xtw WRITER SAMPLE CURSORWRITER JAVA 115 writeEndElement writeStartElement http www w3 o0org TR REC htm140 body xtw xtw xtw writeStartElementC http ww w3 org TR REC htm140 p xtw writeStartElementC http ww w3 org TR REC htm140 a xtw writeCharacters here xtw xtw xtw xtw xtw xtw xtw writeCharacters Moved to
105. avaType is to bound this attribute is required when the parent of the lt javaType gt dec laration is lt globalBindings gt e parseMethod is the name of the parse method to be called during unmar shalling e printMethod is the name of the print method to be called during marshal ling e hasNsContext allows a namespace context to be specified as a second parameter to a print or a parse method can be either true false 1 or 0 By default this attribute is false and in most cases you will not need to change it The lt javaType gt declaration can be used in e A lt globalBindings gt declaration e An annotation element for simple type definitions GlobalBindings and lt basetype gt declarations e A lt property gt declaration See MyDatatypeConverter Class page 54 for an example of how lt javaType gt declarations and the DatatypeConverterInterface interface are implemented in a custom datatype converter class CUSTOMIZATION OVERVIEW 47 Typesafe Enumeration Binding Declarations The typesafe enumeration declarations provide a localized way to map XML simpleType elements to Java typesafe enum classes There are two types of typesafe enumeration declarations you can make e lt typesafeEnumClass gt lets you map an entire simpleType class to type safe enum classes e lt typesafeEnumMember gt lets you map just selected members of a simple Type class to typesafe enum classes In both cases there are two primar
106. ax for the XML to Java datatype binding declarations and the customization namespace prefix are described below Global Binding Declarations Schema Binding Declarations Class Binding Declarations Property Binding Declarations lt javaType gt Binding Declarations Typesafe Enumeration Binding Declarations lt javadoc gt Binding Declarations Customization Namespace Prefix 41 42 USING JAXB Global Binding Declarations Global scope customizations are declared with lt globalBindings gt The syntax for global scope customizations is as follows lt globalBindings gt collectionType collectionType fixedAttributeAsConstantProperty true false 1 o generateIsSetMethod true false 1 o enableFailFastCheck true false 1 o J choiceContentProperty true false 1 o J underscoreBinding asWordSeparator asCharInWord typesafeEnumBase typesafeEnumBase typesafeEnumMemberName generateName generateError enableJavaNamingConventions true false 1 o bindingStyle elementBinding modelGroupBinding lt javaType gt lt javaType gt lt globalBindings gt collectionType can be either indexed or any fully qualified class name that implements java util List fixedAttributeAsConstantProperty can be either true false 1 or Q The default value is false generateIsSetMethod can be either true false 1
107. axonomy for any PostalAddress tModels that use the well known categorization in the uddi org types taxonomy which has the tModel UUID uuid clacf26d 9672 4404 9d70 39b756e62ab4 with a value of postalAddress You can retrieve the tModel overviewDoc which points to the technical detail for the specification of the scheme where the taxonomy structure definition can be found The JAXR equivalent of an overviewDoc is an ExternalLink Running the Client Examples The simple client programs provided with this tutorial can be run from the com mand line You can modify them to suit your needs They allow you to specify the Java WSDP Registry Server for queries and updates To install the Registry Server follow the instructions in Preliminaries Getting Access to a Registry page 175 The examples in the lt INSTALL gt javaeetutorial5 examples jaxr simple src directory are as follows e JAXRQuery java shows how to search a registry for organizations e JAXRQueryByNAICSClassi fication java shows how to search a registry using a common classification scheme e JAXRQueryByWSDLClassi fication java shows how to search a registry for web services that describe themselves by means of a WSDL document e JAXRPublish java shows how to publish an organization to a registry e JAXRDelete java shows how to remove an organization from a registry e JAXRSaveClassificationScheme java shows how to publish a classifi cation scheme specifically a
108. binding compiler will be sufficient to meet your needs There are cases however in which you may want to modify the default bindings Some of these include e Creating API documentation for the schema derived JAXB packages classes methods and constants by adding custom Javadoc tool annota tions to your schemas you can explain concepts guidelines and rules spe cific to your implementation e Providing semantically meaningful customized names for cases that the default XML name to Java identifier mapping cannot handle automati cally for example 35 36 USING JAXB e To resolve name collisions as described in Appendix C 2 1 of the JAXB Specification Note that the JAXB binding compiler detects and reports all name conflicts e To provide names for typesafe enumeration constants that are not legal Java identifiers for example enumeration over integer values e To provide better names for the Java representation of unnamed model groups when they are bound to a Java property or class e To provide more meaningful package names than can be derived by default from the target namespace URI e Overriding default bindings for example e Specify that a model group should be bound to a class rather than a list e Specify that a fixed attribute can be bound to a Java constant e Override the specified default binding of XML Schema built in datatypes to Java datatypes In some cases you might want to introduce an alternative Jav
109. bitrarily and as such provide maximum flexibility for developers However the cost of this flexibility is a potentially large memory footprint and significant processor requirements as the entire representation of the document must be held in memory as objects for the duration of the document processing This may not be an issue when working with small documents but memory and processor requirements can escalate quickly with document size Streaming refers to a programming model in which XML infosets are transmit ted and parsed serially at application runtime often in real time and often from dynamic sources whose contents are not precisely known beforehand Moreover stream based parsers can start generating output immediately and infoset ele ments can be discarded and garbage collected immediately after they are used While providing a smaller memory footprint reduced processor requirements and higher performance in certain situations the primary trade off with stream processing is that you can only see the infoset state at one location at a time in the document You are essentially limited to the cardboard tube view of a doc ument the implication being that you need to know what processing you want to do before reading the XML document Streaming models for XML processing are particularly useful when your appli cation has strict memory limitations as with a cellphone running J2ME or when your application needs to simultaneously
110. bodyElement body addBodyE1ement bodyName Here is the XML it produces lt m GetLastTradePrice xmins m http wombat ztrade com gt lt m GetLastTradePrice gt These lines are what the SOAPBodyElement bodyElement in your code repre sents GetLastTradePrice is its local name m is its namespace prefix and http wombat ztrade com is its namespace URI 130 SOAP WITH ATTACHMENTS API FOR JAVA Here is the SAAJ code QName name new QName symbol SOAPElement symbol bodyElement addChi1ldElement name symbol addTextNodeC SUNW Here is the XML it produces lt symbo1 gt SUNW lt symbol gt The String SUNW is the text node for the element lt symbol gt This String object is the message content that your recipient the stock quote service receives The following example shows how to add multiple SOAPE1ement objects and add text to each of them The code first creates the SOAPBodyElement object purchaseLineItems which has a fully qualified name associated with it That is the QName object for it has a namespace URI a local name and a namespace prefix As you saw earlier a SOAPBodyElement object is required to have a fully qualified name but child elements added to it such as SOAPElement objects can have Name objects with only the local name SOAPBody body message getSOAPBody QName bodyName new QName http sonata fruitsgalore com PurchaseLineItems PO SOAPBodyElement purchaseL
111. both the cursor and event iterator APIs have their own set of interfaces for writing XML streams As with the interfaces for reading streams there are significant differences between the writer APIs for cursor and event iterator The following sections describe how to write XML streams using each of these APIs Using XMLStrea mWriter The XMLStreamWriter interface in the StAX cursor API lets applications write back to an XML stream or create entirely new streams XMLStreamWriter has methods that let you e Write well formed XML e Flush or close the output e Write qualified names Note that XMLStreamWriter implementations are not required to perform well formedness or validity checks on input While some implementations my per form strict error checking others may not The rules you choose to implement are set on properties provided by the XMLOutputFactory class The writeCharacters method is used to escape characters such as amp lt gt and Binding prefixes can be handled by either passing the actual value for the prefix by using the setPrefix method or by setting the property for default ing namespace declarations The following example taken from the StAX specification shows how to instan tiate an output factory create a writer and write XML output XMLOutputFactory output XMLOutputFactory newInstanceQ XMLStreamWriter writer output createXMLStreamWriter writer writeStartDocument writer s
112. cessing an AttachmentPart Object If you receive a message with attachments or want to change an attachment to a message you are building you need to access the attachment The SOAPMessage class provides two versions of the getAttachments method for retrieving its AttachmentPart objects When it is given no argument the method SOAPMes Sage getAttachments returns a java util Iterator object over all the AttachmentPart objects in a message When getAttachments is given a Mime Headers object which is a list of MIME headers getAttachments returns an iterator over the AttachmentPart objects that have a header that matches one of the headers in the list The following code uses the getAttachments method that takes no arguments and thus retrieves all the AttachmentPart objects in the SOAPMessage object message Then it prints the content ID the content type and the content of each AttachmentPart object java util Iterator iterator message getAttachments while Citerator hasNextQ AttachmentPart attachment AttachmentPart iterator nextQ String id attachment getContentIdQ String type attachment getContentTypeQ System out printC Attachment id has content type type if type equals text plain Object content attachment getContent System out printInC Attachment contains n content Adding Attributes An XML element can have one or more attributes that give information about that element An attrib
113. classification schemes 188 information model 172 Java EE application example 206 organizations creating 186 publishing 190 removing 193 overview 171 provider 173 publishing specification concepts 190 WSDL documents 190 querying a registry 181 specification 172 specifying postal addresses 197 submitting data to a registry 186 JAX RPC securing applications 247 service endpoint interfaces XVil JAX RPC applications securing 247 JAX WS defined xv specification xxiv K keyexport command 248 L local names 129 130 M MessageFactory class 124 messages SAAJ accessing elements 126 adding body content 127 attachments 120 creating 124 getting the content 132 overview 118 MIME headers 122 N NAICS 181 using to find organizations 183 202 Name interface 127 names fully qualified 127 130 local 129 130 namespaces 127 prefix 129 nodes SAAJ and 118 O Organization interface 187 organizations creating with JAXR 186 finding by classification 183 202 by name 182 202 using WSDL documents 205 keys 187 193 primary contacts 187 publishing with JAXR 190 202 204 removing with JAXR 193 202 P pkcs12import command 248 point to point connection SAAJ 131 postal addresses retrieving with JAXR 199 203 specifying with JAXR 197 203 prerequisites ix printing the tutorial xiii INDEX 257 providers JAXR 173 proxies xv HTTP setting 179 R registries definition 171 ebXML 172 173 querying with JAXR
114. classifications null null To narrow the search you could use other arguments of the findConcepts method search qualifiers names external identifiers or external links The next step is to go through the concepts find the WSDL documents they cor respond to and display the organizations that use each document Display information about the concepts found Collection specConcepts br getCollectionQ Iterator iter specConcepts iterator if Cliter hasNextQ System out printInC No WSDL specification concepts found else while Citer hasNextQ Concept concept Concept iter next String name getName concept Collection links concept getExternalLinks System out printInC nSpecification Concept n tName name n tKey concept getKey getIdQ n tDescription getDescription concept if Clinks sizeQ gt 0 ExternalLink link QUERYING A REGISTRY 185 CExternalLink links iteratorQ nextQ System out printInC tURL of WSDL document link getExternalURIQ Find organizations that use this concept Collection lt Concept gt specConceptsl new ArrayList lt Concept gt Q specConcepts1l add concept br bqm findOrganizations null null null specConceptsl1 null null Display information about organizations If you find an organization that offers a service you wish to use you can invoke the service using JAX WS Finding Services
115. cm createInternationalString My Service Description service setDescription is Create service bindings Collection lt ServiceBinding gt serviceBindings new ArrayList lt ServiceBinding gt ServiceBinding binding blcm createServiceBinding s blcm createInternationalString My Service Binding Description binding setDescription is allow us to publish a fictitious URI without an error binding setValidateURI false binding setAccessURIC http TheCoffeeBreak com 8080 sb serviceBindings add binding Add service bindings to service service addServiceBindings serviceBindings 189 190 JAVA API FOR XML REGISTRIES Add service to services then add services to organization services add service org addServices services Publishing an Organization The primary method a client uses to add or modify organization data is the saveOrganizations method which creates one or more new organizations in a registry if they did not exist previously If one of the organizations exists but some of the data have changed the saveOrganizations method updates and replaces the data After a client populates an organization with the information it wants to make public it saves the organization The registry returns the key in its response and the client retrieves it Add organization and submit to registry Retrieve key if successful Collection lt Organization gt orgs new ArrayList lt Organ
116. cols although HTTP is used most often Supports interactions with multiple hops between the service consumer and the service provider ADVANTAGES OF MESSAGE SECURITY 233 Some of the characteristics of a web service that make it especially vulnerable to security attacks include the following e Interactions are performed over the Internet using transport protocols that are firewall friendly e Communication is often initiated by service consumers who have no prior relationship with the service provider e The message format is text based Additionally the distributed nature of web service interactions and dependencies might require a standard way to propagate identity and trust between application domains There are several well defined aspects of application security that when prop erly addressed help to minimize the security threat faced by an enterprise These include authentication authorization integrity confidentiality and non repudia tion and more These requirements are discussed in more detail in Characteris tics of Application Security page 946 One of the methods that can be used to address the unique challenges of web ser vices security is message security Message security is discussed in this chapter which includes the following topics e Advantages of Message Security page 233 e Message Security Mechanisms page 235 e Web Services Security Initiatives and Organizations page 236 e Using Message Secu
117. command line For more information about xjc compiler options in general see JAXB Com piler Options page 16 Restrictions for Extemal Binding Customizations There are several rules that apply to binding declarations made in an external binding customization file that do not apply to similar declarations made inline in a source schema e The binding customization file must begin with the jxb bindings version attribute plus attributes for the JAXB and XMLSchema namespaces lt jxb bindings version 1 0 xmIns jxb http java sun com xml ns jaxb xmIns xs http www w3 org 2001 XMLSchema gt e The remote schema to which the binding declaration applies must be iden tified explicitly in XPath notation by means of a jxb bindings declaration specifying schemaLocation and node attributes e schemaLocation URI reference to the remote schema e node XPath 1 0 expression that identifies the schema node within schemaLocation to which the given binding declaration is associated in the case of the initial jxb bindings declaration in the binding cus tomization file this node is typically xs schema For information about XPath syntax see XML Path Language James Clark and Steve DeRose eds W3C 16 November 1999 Available at http www w3 org TR 1999 REC xpath 19991116 e Similarly individual nodes within the schema to which customizations are to be applied must be specified using XPath notation for example 39
118. cuteQuery methods and their helper methods getName getDescription and getKey These methods are very similar to the methods of the same name in the simple examples JAXR Query java and JAXRPublish java The executePublish method uses infor mation in the file PubQueryBeanExample properties to create an organization named The Coffee Enterprise Bean Break The executeQuery method uses the organization name specified in the application client code to locate this organi zation The bean class injects a ConnectionFactory resource It implements a Post Construct method named makeConnection which uses the ConnectionFac tory to create the Connection Finally a PreDestroy method named endConnection closes the Connection Editing the Properties File Before you compile the application edit the PubQueryBeanExamples proper ties file in the same way you edited the JAXRExamples properties file to run the simple examples Feel free to change any of the organization data in the file 207 208 JAVA API FOR XML REGISTRIES Compiling the Source Files To compile the application source files go to the directory lt INSTALL gt javaeetutorial5 examples jaxr clientsession Use the following com mand asant build The build target places the properties file and the class files in the build direc tory Starting the Application Server To run this example you need to start the Application Server Follow the instruc tions in Starting an
119. d gt lt xs complexType gt lt xsS Sequence gt J2S XMLADAPTER FIELD EXAMPLE 71 lt xs element name key minOccurs 0 type xs anyType gt lt xs element name value minOccurs 0 type xs anyType gt lt xs Sequence gt lt xs complexType gt lt xs element gt lt xs Sequence gt lt xs complexType gt lt xs element gt In the default HashMap schema key and value are both elements and are of datatype anyType The XML content will look like this lt basket gt lt entry gt lt key gt 9027 lt gt lt value gt glasstop stove in black lt gt lt entry gt lt entry gt lt key gt 288 lt gt lt value gt wooden spoon lt gt lt entry gt lt basket gt To resolve this issue we wrote two Java classes PurchaseList and PartEntry that reflect the needed schema format for unmarshalling marshalling the content The XML schema generated for these classes is as follows lt xs complexType name PurchaseListType gt lt xS Sequence gt lt xs element name entry type partEntry nillable true maxOccurs unbounded minOccurs Q gt lt xs Sequence gt lt xs complexType gt lt xs complexType name partEntry gt lt xs simpleContent gt lt xs extension base xs string gt lt xSiattribute name key type xs int use required gt lt xs extension gt lt xs simpleContent gt lt xs complexType gt 72 USING JAXB Class AdapterPurchaseListToHashMap implements the XmlAdap
120. d Stopping the Application Server page 28 Creating J AXR Resources To use JAXR in a Java EE application that uses the Application Server you need to access the JAXR_ resource adapter see Implementing a JAXR Client page 174 through a connector connection pool and a connector resource You can create these resources in the Admin Console If you have not done so start the Admin Console as described in Starting the Admin Console page 29 To create the connector connection pool perform the following steps 1 In the tree component expand the Resources node then expand the Con nectors node 2 Click Connector Connection Pools 3 Click New 4 On the General Settings page a Type jaxr pool in the Name field b Choose jaxr ra from the Resource Adapter drop down list c Choose com sun connector jaxr JaxrConnectionFactory the only choice from the Connection Definition drop down list d Click Next 5 On the next page click Finish PACKAGING THE APPLICATION 209 To create the connector resource perform the following steps 1 Under the Connectors node click Connector Resources 2 Click New The Create Connector Resource page appears 3 In the JNDI Name field type eis JAXR 4 Choose jaxr pool from the Pool Name drop down list 5 Click OK If you are in a hurry you can create these objects by executing the following command from the directory lt INSTALL gt javaeetutorial5 examples jaxr clientsession
121. d and assembled using an XMLSignatureFac tory object An application obtains a DOM implementation of XMLSignature Factory by calling the following line of code XMLSignatureFactory fac XMLSignatureFactory getInstance DOM We then invoke various factory methods to create the different parts of the XML Signature object as shown below We create a Reference object passing to it the following e The URI of the object to be signed We specify a URI of which implies the root of the document e The DigestMethod we use SHA1 GENENVELOPED EXAMPLE e A single Transform the enveloped Transform which is required for enveloped signatures so that the signature itself is removed before calcu lating the signature value Reference ref fac newReference C fac newDigestMethod DigestMethod SHA1 null Collections singletonList fac newTransform Transform ENVELOPED TransformParameterSpec null null null Next we create the SignedInfo object which is the object that is actually signed as shown below When creating the SignedInfo we pass as parameters e The CanonicalizationMethod we use inclusive and preserve comments e The SignatureMethod we use DSA e A list of References in this case only one SignedInfo si fac newSignedinfo fac newCanonicalizationMethod CanonicalizationMethod INCLUSIVE_WITH_COMMENTS C14NMethodParameterSpec null fac newSignatureMethod SignatureMethod DSA_SHA1 null Collections
122. der type PurchaseOrderType gt PurchaseOrder java lt xsd element name comment type xsd string gt Comment java lt xsd complexType name PurchaseOrderType gt lt xsd sequence gt lt xsd element name shipTo type USAddress gt lt xsd element name bil1To type USAddress gt lt xsd element ref comment minOccurs 0 gt lt xsd element name items type Items gt lt xsd sequence gt lt xsd attribute name orderDate type xsd date gt lt xsd complexType gt PurchaseOrder Type java ABOUT THE SCHEMA TO JAVA BINDINGS 21 Table 3 7 Schema to Java Bindings for the Basic Examples Continued XML Schema JAXB Binding lt xsd complexType name USAddress gt lt xsd sequence gt lt xsd element name name type xsd string gt lt xsd element name street type xsd string gt lt xsd element name city type xsd string gt lt xsd element name state type xsd string gt lt xsd element name zip type xsd decimal gt lt xsd sequence gt lt xsd attribute name country type xsd NMTOKEN fixed US gt lt xsd complexType gt USAddress java lt xsd complexType name Items gt lt xsd sequence gt lt xsd element name item minOccurs 1 maxOc curs unbounded gt Items java lt xsd comp1lexType gt lt xsd sequence gt lt xsd element name productName type xsd string gt lt xsd element name quantity gt lt xsd simpleType gt lt xsd restriction base
123. ding Organizations by MANAGING REGISTRY DATA Classification page 183 except that you also create a collection of name pat terns and include that in your search Here is an example Define name pattern Collection namePatterns new ArrayListQ namePatterns add Hel loConcept BulkResponse br bqm findConcepts null namePatterns classifications null null Removing Data from the Registry A registry allows you to remove from it any data that you have submitted to it You use the key returned by the registry as an argument to one of the Business LifeCycleManager delete methods deleteOrganizations deleteServices deleteServiceBindings deleteConcepts and others The JAXRDelete sample program deletes the organization created by the JAXR Publish program It deletes the organization that corresponds to a specified key string and then displays the key again so that the user can confirm that it has deleted the correct one String id key getIdQ System out printInC Deleting organization with id id Collection lt Key gt keys new ArrayList lt Key gt keys add key BulkResponse response blcm deleteOrganizations keys Collection exceptions response getException if exceptions null System out printInC Organization deleted Collection retKeys response getCollection Iterator keyIter retKeys iteratorQ Key orgKey null if CkeyIter hasNextQ orgKey Key keyIter nextQ id orgKey ge
124. ding content to the header e Adding content to the SOAPPart object e Adding a document to the SOAP body e Manipulating message content using SAAJ or DOM APIs e Adding attachments e Adding attributes e Using SOAP faults In the section Code Examples page 151 you will see the code fragments from earlier parts of the tutorial in runnable applications which you can test yourself A SAAJ client can send request response messages to web services that are implemented to do request response messaging This section demonstrates how you can do this Creating and Sending a Simple Message This section covers the basics of creating and sending a simple message and retrieving the content of the response It includes the following topics e Creating a message e Parts of a message e Accessing elements of a message e Adding content to the body e Getting a SOAPConnection object e Sending a message e Getting the content of a message Creating a Message The first step is to create a message using a MessageFactory object The SAAJ API provides a default implementation of the MessageFactory class thus mak CREATING AND SENDING A SIMPLE MESSAGE ing it easy to get an instance The following code fragment illustrates getting an instance of the default message factory and then using it to create a message MessageFactory factory MessageFactory newInstance SOAPMessage message factory createMessage As is true of the newInsta
125. directory where lt jwstutorial2Q gt About the Examples This section tells you everything you need to know to install build and run the examples ABOUT THIS TUTORIAL Required Software Java Web Services Tutorial Bundle The example source for the technologies in this tutorial is contained in the Java Web Services Tutorial bundle If you are viewing this online you need to down load the tutorial bundle from http java sun com webservices download webservicespack htm Application Server Sun Java System Application Server Platform Edition 9 is the build and runtime environment for the tutorial examples To build deploy and run the examples you need a copy of the Application Server and the J2SE 5 0 Building the Examples Most of the examples are distributed with a build file for Ant a portable build tool contained in the Java WSDP For information about Ant visit http ant apache org Directions for building the examples are provided in each chapter Most of the tutorial examples are distributed with a configuration file for asant a portable build tool contained in the Application Server This tool is an extension of the Ant tool developed by the Apache Software Foundation http ant apache org The asant utility contains additional tasks that invoke the Application Server administration utility asadmin Directions for building the examples are provided in each chapter Build properties and targets common to al
126. dpoints or as web servlet endpoints Securing web service endpoints is discussed in the following chapters For information on securing web service endpoints of an enterprise bean read Securing Enterprise Beans page 1024 For information on securing web service endpoints of web components read Chapter 9 Securing Web Applications Overview of Message Securty Java EE security is easy to implement and configure and can offer fine grained access control to application functions and data However as is inherent to secu rity applied at the application layer security properties are not transferable to applications running in other environments and only protect data while it is residing in the application environment In the context of a traditional applica tion this is not necessarily a problem but when applied to a web services appli cation Java EE security mechanisms provide only a partial solution The characteristics of a web service that make its security needs different than those of other Java EE applications include the following Loose coupling between the service provider and service consumer Standards based read Web Services Security Initiatives and Organizations page 236 for a discussion of web services security initia tives and organizations Uses XML formatted messages and metadata Highly focused on providing interoperability Platform and programming language neutral Can use a variety of transport proto
127. during the JAXB binding process gt JAXB bind mapped _ _ _ classes follows instances of unmarshal validate Document Objects marshal validate Figure 2 2 Steps in the JAXB Binding Process Take steps from The general steps in the JAXB data binding process are 1 Generate classes An XML schema is used as input to the JAXB binding compiler to generate JAXB classes based on that schema 2 Compile classes All of the generated classes source files and application code must be compiled 3 Unmarshal XML documents written according to the constraints in the source schema are unmarshalled by the JAXB binding framework Note that JAXB also supports unmarshalling XML data from sources other than files documents such as DOM nodes string buffers SAX Sources and so forth 4 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 BINDING BETWEEN XML SCHEMA AND JAVA CLASSES 5 Validate optional The unmarshalling process optionally involves valida tion of the source XML documents before generating the content tree Note that if you modify the content tree in Step 6 below you can also use the JAXB Validate operation to validate the changes before marshalling the content back to an XML document 6 Process content The client application can modi
128. e ClassificationScheme postalScheme blcm createClassificationScheme sn sd String uuid_types uuid clacf26d 9672 4404 9d70 39b756e62ab4 ClassificationScheme uddiOrgTypes ClassificationScheme bqm getRegistryObject uuid_types LifeCycleManager CLASSIFICATION_SCHEME if CuddiOrgTypes null Classification classification blcm createClassification CuddiOrgTypes postalAddress postalAddress postalScheme addClassification classification InternationalString ld blcm createInternationalStringC My Scheme ExternalLink externalLink blcm createExternalLink http www mycom com myscheme xml1 1d postalScheme addExternalLink externalLink Collection lt ClassificationScheme gt schemes new ArrayList lt ClassificationScheme gt Q schemes add cScheme BulkResponse br blcm saveClassificationSchemes schemes The BulkResponse object returned by the saveClassificationSchemes method contains the key for the classification scheme which you need to retrieve 195 196 JAVA API FOR XML REGISTRIES if Cbr getStatus JAXRResponse STATUS_SUCCESS System out printInC Saved ClassificationScheme Collection schemeKeys br getCollection Iterator keysIter schemeKeys iterator while keysIter hasNext Key key Key keysIter next Q System out printInC The postalScheme key is key getIdQ System out printInC Use this key as the scheme uuid in the taxonomy file
129. e music order soap xm1 DOMSource domSource new DOMSource document The following two lines of code access the SOAPPart object using the SOAPMes sage object message and set the new Document object as its content The SOAP Part setContent method not only sets content for the SOAPBody object but also sets the appropriate header for the SOAPHeader object SOAPPart soapPart message getSOAPPart soapPart setContent domSource The XML file you use to set the content of the SOAPPart object must include Envelope and Body elements lt SOAP ENV Envelope xmIns http schemas xmlsoap org soap enve lope gt lt SOAP ENV Body gt lt SOAP ENV Body gt lt SOAP ENV Envelope gt You will see other ways to add content to a message in the sections Adding a Document to the SOAP Body page 136 and Adding Attachments page 137 135 136 SOAP WITH ATTACHMENTS API FOR JAVA Adding a Documentto the SOAP Body In addition to setting the content of the entire SOAP message to that of a DOM Source object you can add a DOM document directly to the body of the mes sage This capability means that you do not have to create a javax xml transform Source object After you parse the document you can add it directly to the message body SOAPBody body message getSOAPBody SOAPBodyElement docElement body addDocument document Manipulating Message Content Using SAA or DOM APis Because SAAJ nodes and elements
130. e You already know that there is only one so calling the next method on it will return the SOAPBodyElement you want Note that the Iterator next method returns a Java Object so you need to cast the Object it returns to a SOAPBodyElement object before assigning it to the variable bodyElement SOAPBody soapBody response getSOAPBody java util Iterator iterator soapBody getChi 1dElements bodyName SOAPBodyElement bodyElement CSOAPBodyElement iterator nextQ String lastPrice bodyElement getValue System out printC The last price for SUNW is System out printIn lastPrice If more than one element had the name bodyName you would have to use a whi le loop using the Iterator hasNext method to make sure that you got all of them while iterator hasNextQ SOAPBodyElement bodyElement CSOAPBodyElement iterator nextQ String lastPrice bodyElement getValueQ System out printC The last price for SUNW is System out printInClastPrice At this point you have seen how to send a very basic request response message and get the content from the response The next sections provide more detail on adding content to messages Adding Content to the Header To add content to the header you create a SOAPHeaderElement object As with all new elements it must have an associated QName object For example suppose you want to add a conformance claim header to the mes sage to state that your message conforms to t
131. e StAX parser maintains a namespace stack which holds information about all XML namespaces defined for the current element and its ances tors The namespace stack is exposed through the javax xml namespace NamespaceContext interface and can be accessed by namespace prefix or URI Choosing Between Cursor and Iterator APis It is reasonable to ask at this point What API should I choose Should I create instances of X MLStreamReader or XMLEventReader Why are there two kinds of APIs anyway Development Goals The authors of the StAX specification targeted three types of developers Library and infrastructure developers Create application servers JAXM JAXB JAX RPC and similar implementations need highly efficient low level APIs with minimal extensibility requirements J2ME developers Need small simple pull parsing libraries and have minimal extensibility needs 87 88 STREAMING API FOR XML J2EE and J2SE developers Need clean efficient pull parsing libraries plus need the flexibility to both read and write XML streams create new event types and extend XML document elements and attributes Given these wide ranging development categories the StAX authors felt it was more useful to define two small efficient APIs rather than overloading one larger and necessarily more complex API Comparing Cursor and Iterator APIs Before choosing between the cursor and iterator APIs you should note a few
132. e The javax xml registry postalAddressScheme property which spec ifies a postal address classification scheme for the connection e The javax xml registry semanticEquivalences property which specifies the semantic equivalences between the JAXR format and the other format For example suppose you want to use a scheme named MyPostalAddress Scheme which you published to a registry with the UUID uuid f7922839 F1F7 9228 c97d ce0b4594736c lt JAXRClassificationScheme id uuid f7922839 f1f7 9228 c97d ceQb4594736c name MyPostalAddressScheme gt 197 198 JAVA API FOR XML REGISTRIES First you specify the postal address scheme using the id value from the JAXR ClassificationScheme element the UUID Case does not matter props setProperty javax xml registry postalAddressScheme uuid 7922839 f1Ff7 9228 c97d ce0b4594736c Next you specify the mapping from the id of each JAXRConcept element in the default JAXR postal address scheme to the id of its counterpart in the scheme you published props setProperty javax xml registry semanticEquivalences urn uuid PostalAddressAttributes StreetNumber uuid f7922839 f1f7 9228 c97d ce0b4594736c StreetAddressNumber urn uuid PostalAddressAttributes Street urn uuid 7922839 f1f7 9228 c97d ce0b4594736c StreetAddress urn uuid PostalAddressAttributes City urn uuid 7922839 f1F7 9228 c97d ceQb4594736c City urn uuid PostalAddressAttributes State
133. e a code sequence very similar to that of finding the key for a saved organization String conceptKeylId null Collection concExceptions concResponse getExceptions Key concKey null if CconcExceptions null System out printInC WSDL Specification Concept saved Collection keys concResponse getCollection Iterator keyIter keys iterator if keyIter hasNextQ concKey Key keyIter nextQ conceptKeyId concKey getIdQ System out printInC Concept key is conceptKeylId Then you can call the getRegistryObject method to retrieve the concept from the registry Concept specConcept Concept bqm getRegistryObject conceptKeyld LifeCycleManager CONCEPT Next you create a Speci ficationLink object for the service binding and set the concept as the value of its SpecificationObject SpecificationLink specLink blcm createSpeci ficationLink specLink setSpeci ficationObject specConcept binding addSpeci ficationLink specLink Now when you publish the organization with its service and service bindings you have also published a link to the WSDL document Now the organization can be found via queries such as those described in Finding Organizations by Classification page 183 If the concept was published by someone else and you don t have access to the key you can find it using its name and classification The code looks very similar to the code used to search for a WSDL document in Fin
134. e tutorial section walks you through creating and populating messages with and without attachment parts 121 122 SOAP WITH ATTACHMENTS API FOR JAVA If a SOAPMessage object has one or more attachments each AttachmentPart object must have a MIME header to indicate the type of data it contains It may also have additional MIME headers to identify it or to give its location These headers are optional but can be useful when there are multiple attachments When a SOAPMessage object has one or more AttachmentPart objects its SOAP Part object may or may not contain message content SAA and DOM The SAAJ APIs extend their counterparts in the org w3c dom package e The Node interface extends the org w3c dom Node interface e The SOAPElement interface extends both the Node interface and the org w3c dom Element interface e The SOAPPart class implements the org w3c dom Document interface e The Text interface extends the org w3c dom Text interface Moreover the SOAPPart of a SOAPMessage is also a DOM Level 2 Document and can be manipulated as such by applications tools and libraries that use DOM For details on how to use DOM documents with the SAAJ API see Adding Con tent to the SOAPPart Object page 134 and Adding a Document to the SOAP Body page 136 Connections All SOAP messages are sent and received over a connection With the SAAJ API the connection is represented by a SOAPConnection object which goes from the sende
135. e unmarshaller will use the identified factory method in this class public class OrderFormsFactory public OrderContext newOrderInstance return new OrderContext public PurchaseOrderType newPurchaseOrderType return new newPurchaseOrderType Xm1TypeCname oContext factoryClass 0rderFormsFactory factoryMethod newOrderInstance public class OrderContext public OrderContextQ In this example a factory method is defined in a class which also contains a standard class constructure Because the factoryMethod value is defined and no factoryClass is defined the factory method newOrderInstance is used during unmarshalling Xm1TypeCname oContext factoryMethod newOrderInstance public class OrderContext public OrderContextQ public OrderContext newOrderInstance Q return new OrderContext Q 76 USING JAXB 4 Steaming API for XML This chapter focuses on the Streaming API for XML StAX a streaming Java based event driven pull parsing API for reading and writing XML docu ments StAX enables you to create bidrectional XML parsers that are fast rela tively easy to program and have a light memory footprint StAX provides is the latest API in the JAXP family and provides an alternative to SAX DOM TrAX and DOM for developers looking to do high performance stream filtering processing and modification particularly with low memory and limited extensibility
136. ean hasNextQ public XMLEvent peek throws XMLStreamException Similarly on the output side of the iterator API you have public interface XMLEventWriter public void flush Q throws XMLStreamException public void close Q throws XMLStreamException public void add XMLEvent e throws XMLStreamException public void add Attribute attribute throws XMLStreamException Iterator Event Types Table 4 2 lists the thirteen XMLEvent types defined in the event iterator API Table 4 2 XMLEvent Types StartDocu Reports the beginning of a set of XML events including encoding ment XML version and standalone properties Reports the start of an element including any attributes and namespace declarations also provides access to the prefix namespace URI and local name of the start tag StartEle ment Reports the end tag of an element Namespaces that have gone out of EndElement scope can be recalled here if they have been explicitly set on their corre sponding StartElement 84 STREAMING API FOR XML Table 4 2 XMLEvent Types Continued Event Type Characters Corresponds to XML CData sections and CharacterData entities Note that ignorable whitespace and significant whitespace are also reported as Character events EntityRef erence Character entities can be reported as discrete events which an applica tion developer can then choose to resolve or pass through unresolved By default entities are
137. ed namespaces are not removed XMLSteamReader Methods XMLStreamReader provides the following methods for retrieving information about namespaces and attributes int getAttributeCount String getAttributeNamespace int index String getAttributeLocalNameCint index String getAttributePrefixCint index String getAttributeTypeCint index String getAttributeValueCint index String getAttributeValue String namespaceUri String localName boolean isAttributeSpecified int index Namespaces can also be accessed using three additional methods int getNamespaceCount String getNamespacePrefixCint index String getNamespaceURICint index Instantiating an XMLSveamReader This example taken from the StAX specification shows how to instantiate an input factory create a reader and iterate over the elements of an XML stream XMLInputFactory f XMLInputFactory newInstance XMLStreamReader r f createXMLStreamReader whileCr hasNextQ r nextQ Using XMLEventReader The XMLEventReader API in the StAX event iterator API provides the means to map events in an XML stream to allocated event objects that can be freely reused and the API itself can be extended to handle custom events STREAMING API FOR XML XMLEventReader provides four methods for iteratively parsing XML streams e next Returns the next event in the stream e nextEvent Returns the next typed XMLEvent e hasNext Returns t
138. egistryService Object After creating the connection the client uses the connection to obtain a Regis tryService object and then the interface or interfaces it will use RegistryService rs connection getRegistryService BusinessQueryManager bqm rs getBusinessQueryManager BusinessLifeCycleManager blcm rs getBusinessLifeCycleManager QUERYING A REGISTRY Typically a client obtains both a BusinessQueryManager object and a Busi nessLifeCycleManager object from the RegistryService object If it is using the registry for simple queries only it may need to obtain only a BusinessQue ryManager object Querying a Registry The simplest way for a client to use a registry is to query it for information about the organizations that have submitted data to it The BusinessQueryManager interface supports a number of find methods that allow clients to search for data using the JAXR information model Many of these methods return a Bulk Response a collection of objects that meets a set of criteria specified in the method arguments The most useful of these methods are as follows e findOrganizations which returns a list of organizations that meet the specified criteria often a name pattern or a classification within a classi fication scheme e findServices which returns a set of services offered by a specified orga nization e findServiceBindings which returns the service bindings information about how to access the ser
139. elements inherit the prefix and URI from the parent element QName name new QName C symbol SOAPElement symbol bodyElement addChi1ldElement name symbol addTextNode SUNW You might recall that the headers and content in a SOAPPart object must be in XML format The SAAJ API takes care of this for you building the appropriate XML constructs automatically when you call methods such as addBodyE lement addChildElement and addTextNode Note that you can call the method addTextNode only on an element such as bodyElement or any child elements that are added to it You cannot call addTextNode on a SOAPHeader or SOAPBody object because they contain elements and not text The content that you have just added to your SOAPBody object will look like the following when it is sent over the wire lt SOAP ENV Envelope xmIns SOAP ENV http schemas xmlsoap org soap envelope gt lt SOAP ENV Body gt lt m GetLastTradePrice xmlns m http wombat ztrade com gt lt symbo1l gt SUNW lt symbo1 gt lt m GetLastTradePrice gt lt SOAP ENV Body gt lt SOAP ENV Envelope gt Let s examine this XML excerpt line by line to see how it relates to your SAAJ code Note that an XML parser does not care about indentations but they are generally used to indicate element levels and thereby make it easier for a human reader to understand Here is the SAAJ code SOAPMessage message messageFactory createMessage SOAPHeader header m
140. emedy this the last part of MyUddiPing java contains code that prints only the text content of the response making it much easier to see the information you want Because the content is in the SOAPBody object the first step is to access it as shown in the following line of code SOAPBody replyBody reply getSOAPBody Next the code displays a message describing the content System out printInC n nContent extracted from the reply message n To display the content of the message the code uses the known format of the reply message First it gets all the reply body s child elements named busi nessList Iterator businessListIterator replyBody getChildElements new QName urn uddi org api_v2 businessList 158 SOAP WITH ATTACHMENTS API FOR JAVA The method getChildElements returns the elements in the form of a java util Iterator object You access the child elements by calling the method next on the Iterator object An immediate child of a SOAPBody object is a SOAPBodyElement object We know that the reply can contain only one businessList element so the code then retrieves this one element by calling the iterator s next method Note that the method Iterator next returns an Object which must be cast to the spe cific kind of object you are retrieving Thus the result of calling businessListIterator next is cast to a SOAPBodyElement object SOAPBodyElement businessList CSOAPBodyElement businessLi
141. end and receive such messages over the Internet some implementations may not support sending and receiving This chapter will help you learn how to use the SAAJ API The SAAJ API conforms to the Simple Object Access Protocol SOAP 1 1 and 1 2 specifications and the SOAP with Attachments specification The SAAJ 1 3 specification defines the javax xml soap package which contains the API for creating and populating a SOAP message This package has all the API neces sary for sending request response messages Request response messages are explained in SOAPConnection Objects page 122 117 118 SOAP WITH ATTACHMENTS API FOR JAVA Note The javax xm1 messaging package defined in the Java API for XML Mes saging JAXM 1 1 specification is not part of the Java EE platform and is not dis cussed in this chapter The JAXM API is available as a separate download from http java sun com xml jaxm This chapter starts with an overview of messages and connections giving some of the conceptual background behind the SAAJ API to help you understand why certain things are done the way they are Next the tutorial shows you how to use the basic SAAJ API giving examples and explanations of the commonly used features The code examples in the last part of the tutorial show you how to build an application Overview of SAA This section presents a high level view of how SAAJ messaging works and explains concepts in general terms Its goal is
142. ent class Create an instance of Comment public primer po Comment createComment String value throws javax xml bind JAXBException return new primer po imp1 CommentImp value Create an instance of Items public primer po Items createItems throws javax xml bind JAXBException return primer po Items newInstance primer po Items class Create an instance of PurchaseOrderType public primer po PurchaseOrderType createPurchaseOrderTypeQ throws javax xml bind JAXBException SCHEMA DERIVED JAXB CLASSES 27 return primer po PurchaseOrderType newInstance primer po PurchaseOrderType class Purc haseOrderjava In PurchaseOrder java below e The PurchaseOrder class is part of the primer po package e PurchaseOrder is a public interface that extends javax xml bind Ele ment and primer po PurchaseOrderType e Content in instantiations of this class bind to the XML schema element named purchaseOrder The PurchaseOrder java code looks like this package primer po public interface PurchaseOrder extends javax xml bind Element primer po PurchaseOrderType Purc haseOrdertype java In PurchaseOrderType java below e The PurchaseOrderType class is part of the primer po package e Content in instantiations of this class bind to the XML schema child ele ment named PurchaseOrderType e PurchaseOrderType is a public interface that provides t
143. entation for generated package primer myPo lt body gt gt lt jxb javadoc gt lt jxb package gt lt jxb nameXm1Transform gt lt jxb elementName suffix Element gt lt jxb nameXm1Transform gt lt jxb schemaBindings gt e lt jxb package name primer myPo gt specifies the primer myPo as the package in which the schema derived classes should be generated e lt jxb nameXm1Transform gt specifies that all generated Java element inter faces should have Element appended to the generated names by default For example when the JAXB compiler is run against this schema the ele ment interfaces CommentElement and PurchaseOrderElement will be generated By contrast without this customization the default binding would instead generate Comment and PurchaseOrder This customization is useful if a schema uses the same name in different symbol spaces for example in global element and type definitions In such cases this customization enables you to resolve the collision with one declaration rather than having to individually resolve each collision with a separate binding declaration 52 USING JAXB e lt jxb javadoc gt specifies customized Javadoc tool annotations for the primer myPo package Note that unlike the lt javadoc gt declarations at the class level below the opening and closing lt body gt tags must be included when the lt javadoc gt declaration is made at the package level Class Binding Declarations The
144. ented by a corresponding interface except for the KeyInfo structures which are included in their own package and are discussed in the next paragraph These interfaces include SignedInfo CanonicalizationMethod SignatureMethod Reference Transform DigestMethod XMLObject Mani fest SignatureProperty and SignatureProperties The XMLSignature Factory class is an abstract factory that is used to create objects that implement these interfaces The javax xml crypto dsig keyinfo package contains interfaces that repre sent most of the KeyInfo structures defined in the W3C XML digital signature recommendation including KeyInfo KeyName KeyValue X509Data X509IssuerSerial RetrievalMethod and PGPData The KeyInfoFactory class is an abstract factory that is used to create objects that implement these interfaces The javax xml crypto dsig spec package contains interfaces and classes representing input parameters for the digest signature transform or canonical ization algorithms used in the processing of XML signatures Finally the javax xml crypto dom and javax xml crypto dsig dom pack ages contains DOM specific classes for the javax xml crypto and SERVICE PROVIDERS 217 javax xml crypto dsig packages respectively Only developers and users who are creating or using a DOM based XMLSignatureFactory or KeyInfo Factory implementation should need to make direct use of these packages Service Providers A JSR 105 cryptographic service
145. enveloped XML Signature indented and formatted for readability is as follows lt xml version 1 0 encoding UTF 8 gt lt Envelope xmlns urn envelope gt lt Signature xmIns http ww w3 org 2000 09 xmldsig gt lt SignedInfo gt lt CanonicalizationMethod Algorithm http www w3 org TR 2001 REC xml c14n 20010315 WithComments gt lt SignatureMethod Algorithm http www w3 org 2000 09 xmldsig dsa shal gt lt Reference URI gt lt Transforms gt lt Transform Algorithm http www w3 org 2000 09 xmldsig enveloped signature gt lt Transforms gt lt DigestMethod Algorithm http www w3 org 2000 09 xmldsig shal gt lt DigestValue gt uocoqbWYa5VCqcJ CbuymBKqm17vY lt DigestValue gt lt Reference gt lt SignedIinfo gt lt SignatureValue gt EXAMPLE OF AN XML SIGNATURE 219 KedJuTob5gtvYx9qM3k3gm7kbLBwVbEQR126S2tmXjqNND7MRGtoew lt SignatureValue gt lt KeyInfo gt lt KeyValue gt lt DSAKeyValue gt lt P gt KaCzo4Syrom78z3EQ5SbbB4sF7ey80etKII864WF64B81uRpH5t9jQTxe Eu ImbzRMqzVDZkVG9xD7nN1LkuFw lt P gt lt Q gt 1i17dzDacuo67Jg7mtqEm2TRUOMU lt Q gt lt G gt Z4Rxsnqc9E7pGknFFH2xqaryRPBaQ 1khpMdLRQnG541Awtx XPaF5Bpsy4pNwMOHCB7i NU NogpsQW5Qvn I MpA lt G gt lt Y gt qVv38IqrwJGOV mZQvRVi LOHW9Zj 84nDC4j08PQaxi 1gb6d 475yhMjSc BrIVC58w3ydbkK Ri 40KbaRZ1YeRA lt Y gt lt DSAKeyValue gt lt KeyValue gt lt KeyInfo gt lt Signature gt lt Envelope gt The Sign
146. equired to buffer the last StartElement until an event other than Attribute or Namespace is added or encountered in the stream This means that when you add an Attribute or a Namespace to a stream it is appended the current StartElement event You can use the Characters method to escape characters like amp lt gt and The setPrefix method can be used to explicitly bind a prefix for use dur ing output and the getPrefix method can be used to get the current pre fix Note that by default XMLEventWriter adds namespace bindings to its internal namespace map Prefixes go out of scope after the corresponding EndElement for the event in which they are bound SUN S STREAMING PARSER IMPLEMENTATION Sun s Steaming Parser Implementation The Sun Java System Application Server SJSAS PE 9 0 package includes Sun Microsystem s JSR 173 StAX implementation called the Sun Java Streaming XML Parser SJSXP The SJSXP is a high speed non validating W3C XML 1 0 and Namespace 1 0 compliant streaming XML pull parser built upon the Xerces2 codebase In Sun s SJSXP implementation the Xerces2 lower layers particularly the Scan ner and related classes have been redesigned to behave in a pull fashion In addi tion to the changes the lower layers the SJSXP includes additional StAX related functionality and many performance enhancing improvements The SJSXP is implemented in appserv ws jar and javaee jar both of which are loca
147. er s private key It is typically created through the use of a hash function and a private signing function encrypting with the signer s private key but there are other methods For more information on cryptography please read this document RSA Labora tories Frequently Asked Questions About Today s Cryptography Version 4 1 available at http www rsasecurity com rsalabs node asp id 2152 Some of the text in this section was excerpted by permission from this docu ment Web Services Securty Initiatives and Organizations The following organizations work on web services security specifications guide lines and tools e The World Wide Web Consortium W3C e Organization for Advancement of Structured Information Standards OASIS e Web Services Interoperability Organization WS D e Java Community Process JCP Basically the JCP W3C and OASIS are developing specifications related to web services security WS I creates profiles that recommend what to implement from various specifications and provides direction on how to implement the specifications The following sections briefly discuss the specifications and pro files being developed by each organization WSC Specifications The mission of the World Wide Web Consortium W3C according to its Web site at http www w3 org is to lead the World Wide Web to its full potential by developing protocols and guidelines that ensure long term growth for the web W3C prima
148. ervice Hel loWorld lt endpoint address uri gt lt message security binding auth layer SOAP gt lt message security gt lt message gt lt java method gt lt method name gt ejbTaxCal c lt method name gt lt java method gt lt message gt lt message gt lt java method gt lt method name gt sayHel 1o lt method name gt USING THE APPLICATION SERVER MESSAGE SECURITY IMPLEMENTATION lt java method gt lt message gt lt request protection auth source content gt lt response protection auth source content gt lt message security gt lt message security binding gt lt webservice endpoint gt lt ejb gt lt enterprise beans gt lt sun ejb jar gt In this example the message security binding element has been added to a web service endpoint for an enterprise bean The elements highlighted in bold above are described briefly below and in more detail in the Application Server s Application Deployment Guide A link to this document is provided in Further Information page 251 e message security binding This element specifies a custom authentica tion provider binding for a parent webservice endpoint or port info element by binding to a specific provider and or by specifying the message security requirements enforced by the provider It contains the attributes auth layer and provider id optional auth layer This element specifies the message layer at which authen tication is performed The value m
149. es not have necessary info Detail detail fault addDetailQ QName entryName new QNameC http gizmos com orders order PO USING SOAP FAULTS DetailEntry entry detail addDetailEntry CentryName entry addTextNode Quantity element does not have a value QName entryName2 new QNameC http gizmos com orders order PO DetailEntry entry2 detail addDetailEntry CentryName2 entry2 addTextNode Incomplete address no zip code See SOAPFaultTest java page 168 for an example that uses code like that shown in this section The SOAP 1 1 and 1 2 specifications define slightly different values for a fault code Table 5 1 lists and describes these values Table 5 1 SOAP Fault Code Values SOAP 1 1 SOAP 1 2 Description VersionMismatch VersionMismatch The namespace or local name for a SOAPEn ve lope object was invalid MustUnderstand MustUnderstand An immediate child element of a SOAP Header object had its mustUnderstand attribute set to true and the processing party did not understand the element or did not obey it Client Sender The SOAPMessage object was not formed correctly or did not contain the information needed to succeed Server Receiver The SOAPMessage object could not be pro cessed because of a processing error not because of a problem with the message itself DataEncodingUnknown A SOAP header block or SOAP body child element information
150. es not include a key the registry returns the new key when it accepts the newly created organization The b1cm object in the following code fragment is the BusinessLifeCycleManager object returned in Obtaining and Using a RegistryService Object page 180 An Internation alString object is used for string values that may need to be localized Create organization name and description InternationalString s blcm createInternationalStringC The Coffee Break Organization org blcm createOrganization s s blcm createInternationalStringC Purveyor of the finest coffees Established 1950 org setDescription s Create primary contact set name User primaryContact blcm createUser PersonName pName blcm createPersonName Jane Doe primaryContact setPersonName pName Set primary contact phone number TelephoneNumber tNum blcm createTelephoneNumber tNum setNumber 800 555 1212 Collection lt TelephoneNumber gt phoneNums new ArrayList lt TelephoneNumber gt phoneNums add tNum primaryContact setTelephoneNumbers phoneNums 187 188 JAVA API FOR XML REGISTRIES Set primary contact email address EmailAddress emailAddress blcm createEmai lAddress jane doe TheCoffeeBreak com Collection lt EmailAddress gt emailAddresses new ArrayList lt Emai lAddress gt emai lAddresses add emai lAddress primaryContact setEmai lAddresses emai lAddresses Set primary co
151. es the same parameters and does essentially the same thing It takes a Java Object containing the content and a String giving the content type As with AttachmentPart setContent the Object can be a String a stream a javax xm transform Source object or a javax activation DataHandler object The other method for creating an AttachmentPart object with content takes a DataHandler object which is part of the JavaBeans Activation Framework JAF Using a DataHandler object is fairly straightforward First you create a java net URL object for the file you want to add as content Then you create a DataHand ler object initialized with the URL object URL url new URLC http greatproducts com gizmos img jpg DataHandler dataHandler new DataHandler url AttachmentPart attachment message createAttachmentPart dataHandler attachment setContentIdC attached_image message addAttachmentPart attachment You might note two things about this code fragment First it sets a header for Content ID using the method setContentId This method takes a String that can be whatever you like to identify the attachment Second unlike the other methods for setting content this one does not take a String for Content Type This method takes care of setting the Content Type header for you something ADDING ATTRIBUTES that is possible because one of the things a DataHandler object does is to deter mine the data type of the file it contains Ac
152. essInfo getChildElements new QName urn uddi org api_v2 name while CnameIterator hasNextQ businessName CSOAPElement nameIterator next Q System out printInC Company name businessName getValue Iterator descriptionIterator businessInfo getChildElements new QName urn uddi org api_v2 description while descriptionIterator hasNext Q SOAPElement businessDescription CSOAPElement descriptionIterator nextQ System out printInC Description businessDescription getValue System out printInC Finally the program closes the connection connection close Running MyUddiPing You are now ready to run MyUddiPing The run target takes two arguments but you need to supply only one of them The first argument is the file uddi prop erties which is supplied by a property that is set in build properties The other argument is the first letters of the name of the business for which you want to get a description and you need to supply this argument on the command line Note that any property set on the command line overrides any value set for that property in the build xm1 file Use a command like the following to run the example asant run Dbusiness name the 160 SOAP WITH ATTACHMENTS API FOR JAVA The program output depends on the contents of the registry For example Content extracted from the reply message Company name The Coffee Break Description Purv
153. essage getSOAPHeader SOAPBody body message getSOAPBody CREATING AND SENDING A SIMPLE MESSAGE 129 Here is the XML it produces lt SOAP ENV Envelope xmIns SOAP ENV http schemas xmlsoap org soap envelope gt lt SOAP ENV Header gt lt SOAP ENV Body gt lt SOAP ENV Body gt lt SOAP ENV Envelope gt The outermost element in this XML example is the SOAP envelope element indicated by SOAP ENV Envelope Note that Envelope is the name of the ele ment and SOAP ENV is the namespace prefix The interface SOAPEnve lope repre sents a SOAP envelope The first line signals the beginning of the SOAP envelope element and the last line signals the end of it everything in between is part of the SOAP envelope The second line is an example of an attribute for the SOAP envelope element Because a SOAP envelope element always contains this attribute with this value a SOAPMessage object comes with it automatically included xmIns stands for XML namespace and its value is the URI of the namespace associated with Envelope The next line is an empty SOAP header We could remove it by calling header detachNode after the getSOAPHeader call The next two lines mark the beginning and end of the SOAP body represented in SAAJ by a SOAPBody object The next step is to add content to the body Here is the SAAJ code QName bodyName new QNameC http wombat ztrade com GetLastTradePrice m SOAPBodyElement
154. etChildElements getContents iter2 indent 164 SOAP WITH ATTACHMENTS API FOR JAVA else text Text node String content text getValueQ System out printInCindent Content is content Examining DOMSic Example DOMSrcExample differs from DOMExample in only a few ways First after it parses the document DOMSrcExample uses the document to create a DOM Source object This code is the same as that of DOMExample except for the last line static DOMSource domSource try DocumentBuilder builder factory newDocumentBui lder Document document builder parse new File Cargs domSource new DOMSource document Then after DOMSrcExample creates the message it does not get the header and body and add the document to the body as DOMExample does Instead DOM SrcExample gets the SOAP part and sets the DOMSource object as its content Create a message SOAPMessage message messageFactory createMessage Get the SOAP part and set its content to domSource SOAPPart soapPart message getSOAPPartQ soapPart setContent domSource The example then uses the getContents method to obtain the contents of both the header if it exists and the body of the message The most important difference between these two examples is the kind of docu ment you can use to create the message Because DOMExample adds the docu ment to the body of the SOAP message you can use any valid XML file to
155. etPrefix c http c writer setDefaultNamespace http c writer writeStartElement http c a writer writeAttributeC b blah writer writeNamespace c http c writer writeDefaultNamespace http c 95 96 STREAMING API FOR XML writer setPrefix d http c writer writeEmptyElementC http c d writer writeAttributeC http c chris fry writer writeNamespace d http c writer writeCharacters foo bar foo writer writeEndElement writer flushQ This code generates the following XML new lines are non normative lt xml version 1 encoding utf 8 gt lt a b blah xmIns c http c xmIns http c gt lt d d d chris fry xmins d http c gt foo bar foo lt a gt Using XMLEventWiiter The XMLEventWriter interface in the StAX event iterator API lets applications write back to an XML stream or create entirely new streams This API can be extended but the main API is as follows public interface XMLEventwWriter public void flushQ throws XMLStreamException public void closeQ throws XMLStreamException public void add XMLEvent e throws XMLStreamException other methods not shown Instances of XMLEventWriter are created by an instance of XMLOutputFactory Stream events are added iteratively and an event cannot be modified after it has been added to an event writer instance Athibutes Escaping Characters Binding Prefixes StAX implementations are r
156. ew of SAAJ 118 Messages 118 Connections 122 Tutorial 123 Creating and Sending a Simple Message 124 Adding Content to the Header 133 Adding Content to the SOAPPart Object 134 Adding a Document to the SOAP Body 136 vi Chapter 6 CONTENTS Manipulating Message Content Using SAAJ or DOM APIs 136 Adding Attachments 137 Adding Attributes 139 Using SOAP Faults 145 Code Examples 151 Request java 152 MyUddiPing java 153 HeaderExample java 160 DOMExample java and DOMSrcExample java 162 Attachments java 166 SOAPFaultTest java 168 Further Information 170 Java API for XML Registres 171 Overview of JAXR 171 What Is a Registry 171 What Is JAXR 172 JAXR Architecture 173 Implementing a JAXR Client 174 Establishing a Connection 175 Querying a Registry 181 Managing Registry Data 186 Using Taxonomies in JAXR Clients 194 Running the Client Examples 199 Before You Compile the Examples 200 Compiling the Examples 201 Running the Examples 201 Using JAXR Clients in Java EE Applications 206 Coding the Application Client MyAppClient java 207 Coding the PubQuery Session Bean 207 Editing the Properties File 207 Compiling the Source Files 208 Starting the Application Server 208 Creating JAXR Resources 208 Packaging the Application 209 Deploying the Application 210 Running the Application Client 210 Further Information 210 Chapter 7 Chapter 8 CONTENTS Java XML Digital Signature API 213 How XW
157. ewInstanceQ We must also make the factory namespace aware dbf setNamespaceAware true Next we use the factory to get an instance of a DocumentBui Ider which is used to parse the document DocumentBuilder builder dbf newDocumentBui lderQ Document doc builder parse new FileInputStream argv 227 228 JAVA XML DIGITAL SIGNATURE API Creating a Public Key Pair We generate a public key pair Later in the example we will use the private key to generate the signature We create the key pair with a KeyPairGenerator In this example we will create a DSA KeyPair with a length of 512 bytes KeyPairGenerator kpg KeyPairGenerator getInstance DSA kpg initialize 512 KeyPair kp kpg generateKeyPair Q In practice the private key is usually previously generated and stored in a Key Store file with an associated public key certificate Creating a Signing Context We create an XML Digital Signature XMLSignContext containing input parame ters for generating the signature Since we are using DOM we instantiate a DOM SignContext a subclass of XMLSignContext and pass it two parameters the private key that will be used to sign the document and the root of the document to be signed DOMSignContext dsc new DOMSignContext kp getPrivate doc getDocumentElement Assembling the XML Signature We assemble the different parts of the Signature element into an XMLSignature object These objects are all create
158. exType named PurchaseOrderType primer po USAddress java Public interface that binds to the schema complexType named USAddress primer po imp1 CommentImp1 java Implementation of Comment java primer po imp1 ItemsImp1 java Implementation of Items java primer po imp1 PurchaseOrderImp1 java Implementation of PurchaseOrder java 20 USING JAXB Table 3 6 Schema Derived JAXB Classes in the Basic Examples Continued jets Desert OO primer po imp1 PurchaseOrderType Implementation of PurchaseOrderType java Imp1 java primer po imp1 USAddressImp1 java Implementation of USAddress java Note You should never directly use the generated implementation classes that is Imp1 java in the lt packagename gt imp1 directory These classes are not directly referenceable because the class names in this directory are not standardized by the JAXB specification The ObjectFactory method is the only portable means to cre ate an instance of a schema derived interface There is also an ObjectFac tory newInstance Class JAXBinterface method that enables you to create instances of interfaces These classes and their specific bindings to the source XML schema for the basic examples are described below Table 3 7 Schema to Java Bindings for the Basic Examples XML Schema JAXB Binding lt xsd schema xmIns xsd http www w3 org 2001 XMLSchema gt lt xsd element name purchaseOr
159. examples stax event directory EventParse java demonstrates how to use the StAX event API to read an XML document EVENT SAMPLE EVENTPARSE JAVA 107 Creating an Input Factory The first step is to create a new instance of XMLInputFactory XMLInputFactory factory XMLInputFactory newInstance System out printInC FACTORY factory Creating an Event Reader The next step is to create an instance of XMLEventReader XMLEventReader r factory createXMLEventReader filename new FileInputStream filename Creating an Event Iterator The third step is to create an event iterator XMLEventReader r factory createXMLEventReader filename new FileInputStream filename whileCr hasNextQ XMLEvent e r nextEvent System out printIn Ce toStringQ Getting the Event Steam The final step is to get the underlying event stream public final static String getEventTypeStringCint eventType switch eventType case XMLEvent START_ELEMENT return START_ELEMENT case XMLEvent END_ELEMENT return END_ELEMENT case XMLEvent PROCESSING_INSTRUCTION return PROCESSING_INSTRUCTION case XMLEvent CHARACTERS return CHARACTERS case XMLEvent COMMENT return COMMENT case XMLEvent START_DOCUMENT 108 STREAMING API FOR XML return START_DOCUMENT case XMLEvent END_DOCUMENT return END_DOCUMENT case XMLEvent ENTITY_REFERENCE return ENTITY_REFERENCE case XMLEvent ATTRIBUTE return ATTRIBU
160. ext few lines begin the definition of the class MyUddiPing which starts with the definition of its main method The first thing it does is to check to see whether two arguments were supplied If they were not it prints a usage message and exits The usage message mentions only one argument the other is supplied by the build xm1 target public class MyUddiPing public static void main String args try if Cargs length 2 System err printInC Usage asant run _Dbusiness name lt name gt System exit 1 The following lines create a java util Properties object that contains the system properties and the properties from the file uddi properties which is in the myuddi ping directory Properties myprops new Properties myprops load new FileInputStream args Properties props System getProperties Enumeration propNames myprops propertyNames while propNames hasMoreElements String s String propNames nextElementQ props setProperty s myprops getProperty s The next four lines create a SOAPMessage object First the code gets an instance of SOAPConnectionFactory and uses it to create a connection Then it gets an instance of a SOAP 1 1 MessageFactory using the MessageFactory instance to create a message SOAPConnectionFactory soapConnectionFactory SOAPConnectionFactory newInstance SOAPConnection connection soapConnectionFactory createConnectionQ MessageFactory
161. eyor of the finest coffees Established 1950 The program will not return any results until you have run the examples in Chap ter 6 If you want to run MyUddiPing again you may want to start over by deleting the build directory and the class file it contains You can do this by typing the fol lowing at the command line asant clean HeaderExample java The example HeaderExample java based on the code fragments in the section Adding Attributes page 139 creates a message that has several headers It then retrieves the contents of the headers and prints them The example generates either a SOAP 1 1 message or a SOAP 1 2 message depending on arguments you specify You will find the code for HeaderExample in the following direc tory lt INSTALL gt javaeetutorial5 examples saaj headers src Running HeaderExample To run HeaderExample you use the file build xml that is in the directory lt INSTALL gt javaeetutorial5 examples saaj headers To run HeaderExample use one of the following commands asant run Dsoap 1 1 asant run Dsoap 1 2 This command executes the prepare build and run targets in the build xml and targets xm 1 files HEADEREXAMPLE JAVA 161 When you run HeaderExample to generate a SOAP 1 1 message you will see output similar to the following Request Message lt SOAP ENV Envelope xmIns SOAP ENV http schemas xmlsoap org soap envelope gt lt SOAP ENV Header gt lt ns orderDesk
162. f the XMLEventAllocator interface New instances of the abstract class XMLOutputFactory are created by calling the newInstance method on the class The static method XMLOutputFac tory newInstance is then used to create a new factory instance The algo rithm used to obtain the instance is the same as for XMLInputFactory but references the javax xml stream XMLOutputFactory system property XMLOutputFactory supports only one property javax xml stream isRepair ingNamespaces This property is required and its purpose is to create default RESOURCES NAMESPACES AND ERRORS prefixes and associate them with Namespace URIs See the StAX specification for a more information XMLEventFac tory New instances of the abstract class XMLEventFactory are created by calling the newInstance method on the class The static method XMLEventFac tory newInstance is then used to create a new factory instance This factory references the javax xml stream XMLEventFactory property to instantiate the factory The algorithm used to obtain the instance is the same as for XMLInput Factory and XMLOutputFactory but references the javax xm1 stream XMLEv entFactory system property There are no default properties for XMLEventFactory Resources Namespaces and Enors The StAX specification handles resource allocation attributes and namespace and errors and exceptions as described below Resource Resolution The XMLResolver interface provides a mean
163. ficate elements contained in a KeyInfo The implementation of the KeyValueKeySelector is as follows private static class KeyValueKeySelector extends KeySelector public KeySelectorResult select KeyInfo keyInfo KeySelector Purpose purpose AlgorithmMethod method XMLCryptoContext context throws KeySelectorException if keyInfo null throw new KeySelectorException Null KeyInfo object SignatureMethod sm SignatureMethod method List list keyInfo getContent for Cint i 0 i lt list size i 226 JAVA XML DIGITAL SIGNATURE API XMLStructure xmlStructure XMLStructure list get i if xmlStructure instanceof KeyValue PublicKey pk null try pk C KeyValue xm1Structure getPublicKeyQ catch KeyException ke throw new KeySelectorException ke make sure algorithm is compatible with method if CalgEquals sm getAlgorithm pk getAlgorithm return new SimpleKeySelectorResult pk throw new KeySelectorException No KeyValue element found static boolean algEquals String algURI String algName if algName equalsIgnoreCase DSA amp amp algURI equalsIgnoreCase SignatureMethod DSA_SHA1 return true else if algName equalsIgnoreCase RSA amp amp algURI equalsIgnoreCase SignatureMethod RSA_SHA1 return true else return false genenveloped Example The code discussed in this section is in the GenEnveloped java file in the
164. following code shows the class binding declarations in po xsd lt xsd complexType name PurchaseOrderType gt lt xsd annotation gt lt xsd appinfo gt lt jxb class name POType gt lt jxb javadoc gt A amp lt b gt Purchase Order amp lt b gt consists of addresses and items lt jxb javadoc gt lt jxb class gt lt xsd appinfo gt lt xsd annotation gt lt xsd complexType gt The Javadoc tool annotations for the schema derived POType class will contain the description A amp 1t b gt Purchase Order amp lt b gt consists of addresses and items The amp 1t is used to escape the opening bracket on the lt b gt HTML tags Note When a lt class gt customization is specified in the appinfo element of a com plexType definition as it is here the complexType definition is bound to a Java con tent interface Later in po xsd another lt javadoc gt customization is declared at this class level but this time the HTML string is escaped with CDATA lt xsd annotation gt lt xsd appinfo gt lt jxb class gt lt jxb javadoc gt lt CDATA First line of documentation for a lt b gt USAddress lt b gt gt CUSTOMIZE INLINE EXAMPLE 53 lt jxb javadoc gt lt jxb class gt lt xsd appinfo gt lt xsd annotation gt Note If you want to include HTML markup tags in a lt jaxb javadoc gt customiza tion you must enclose the data within a CDATA section or escape all left angle brack ets using amp 1
165. fragment shows how to find all the organizations in the registry whose names begin with a speci fied string qString and sort them in alphabetical order Define find qualifiers and name patterns Collection lt String gt findQualifiers new ArrayList lt String gt Q findQualifiers add FindQualifier SORT_BY_NAME_DESC Collection lt String gt namePatterns new ArrayList lt String gt Q namePatterns add qString Find orgs whose names begin with qString BulkResponse response bqm findOrganizations findQualifiers namePatterns null null null null Collection orgs response getCollection The last four arguments to findOrganizations allow you to search using other criteria than the name classifications specification concepts external identifiers or external links Finding Organizations by Classification page 183 describes searching by classification and by specification concept The other searches are less common and are not described in this tutorial A client can use percent signs to specify that the query string can occur any where within the organization name For example the following code fragment performs a case sensitive search for organizations whose names contain qString Collection lt String gt findQualifiers new ArrayList lt String gt Q findQualifiers add FindQualifier CASE_SENSITIVE_MATCH Collection lt String gt namePatterns new ArrayList lt String gt Q namePatterns add qString
166. fy the connection property com sun xml l registry userTaxonomyFi le names in your client program You set the property as follows props setProperty C com sun xml registry userTaxonomyFilenames c mydir xxx xml c mydir xxx2 xm1 Use the vertical bar as a separator if you specify more than one file name Specifying Postal Addresses The JAXR specification defines a postal address as a structured interface with attributes for street city country and so on The UDDI specification on the other hand defines a postal address as a free form collection of address lines each of which can also be assigned a meaning To map the JAXR Postal Address format to a known UDDI address format you specify the UDDI format as a ClassificationScheme object and then specify the semantic equivalences between the concepts in the UDDI format classification scheme and the com ments in the JAXR PostalAddress classification scheme The JAXR Postal Address classification scheme is provided by the implementation of JAXR in the Application Server In the JAXR API a PostalAddress object has the fields streetNumber street city state postalCode and country In the implementation of JAXR in the Application Server these are predefined concepts in the jaxrconcepts xm1 file within the ClassificationScheme named PostalAddressAttributes To specify the mapping between the JAXR postal address format and another format you set two connection properties
167. fy the XML data repre sented by the Java content tree by means of interfaces generated by the binding compiler 7 Marshal The processed content tree is marshalled out to one or more XML output documents The content may be validated before marshalling More About Unmarshalling Unmarshlling provides a client application the ability to convert XML data into JAXB derived Java objects More About Marshalling Marshalling provides a client application the ability to convert a JAXB derived Java object tree back into XML data By default the Marshal ler uses UTF 8 encoding when generating XML data Client applications are not required to validate the Java content tree before mar shalling There is also no requirement that the Java content tree be valid with respect to its original schema in order to marshal it back into XML data More About Validation Validation is the process of verifying that an XML document meets all the con straints expressed in the schema JAXB 1 0 provided validation at unmarshal time and also enabled on demand validation on a JAXB content tree JAXB 2 0 only allows validation at unmarshal and marshal time A web service processing model is to be lax in reading in data and strict on writing it out To meet that model validation was added to marshal time so one could confirm that they did not invalidate the XML document when modifying the document in JAXB form REPRESENTING XML CONTENT Representing XML Content
168. ge instructions for the examples used in this chapter including how to build and run the applications using the Ant build tool and provides details about the default schema to JAXB bindings used in these examples Desc nption This chapter describes three sets of examples e The Basic examples Unmarshal Read Modify Marshal Unmarshal Vali date Pull Parser demonstrate basic JAXB concepts like ummarshalling marshalling validating XML content and parsing XML data e The Customize examples Customize Inline Datatype Converter External Customize Fix Collides demonstrate various ways of customizing the binding of XML schemas to Java objects e The Java to Schema examples show how to use annotations to map Java classes to XML schema The Basic and Customize examples are based on a Purchase Order scenario With the exception of the Fix Collides example each uses an XML document po xml1 written against an XML schema po xsd DESCRIPTION 13 Table 3 1 briefly describes the Basic examples Table 3 1 Basic JAXB Examples Unmarshal Read Exam Demonstrates how to unmarshal an XML document into a Java ple content tree and access the data contained within it Modify Marshal Exam ple Demonstrates how to modify a Java content tree Unmarshal Validate Demonstrates how to enable validation during unmarshalling Example Demonstrates how to use the StAX pull parser to parse a portion Pull Parser Example ofan XM docu
169. gned to the QName object attributeName The examples in DOMExample java and DOMSrcExample java page 162 use code similar to this Iterator iterator person getAl lAttributesAsQNames while Citerator hasNextQ QName attributeName QName iterator nextQ System out printInC Attribute name is attributeName toString Q System out printInC Attribute value is element getAttributeValue attributeName The following line of code removes the attribute named id from person The variable successful will be true if the attribute was removed successfully boolean successful person removeAttribute attributeName In this section you have seen how to add retrieve and remove attributes This information is general in that it applies to any element The next section dis cusses attributes that can be added only to header elements ADDING ATTRIBUTES Header Attibutes Attributes that appear in a SOAPHeaderElement object determine how a recipient processes a message You can think of header attributes as offering a way to extend a message giving information about such things as authentication trans action management payment and so on A header attribute refines the meaning of the header whereas the header refines the meaning of the message contained in the SOAP body The SOAP 1 1 specification defines two attributes that can appear only in SOAP HeaderElement objects actor and mustUnderstand The SOAP 1 2 specif
170. hapter describes the JAXB architecture functions and core concepts You should read this chapter before proceeding to Chapter 3 which provides sample code and step by step procedures for using JAXB J AXB Architecture This section describes the components and interactions in the JAXB processing model BINDING BETWEEN XML SCHEMA AND JAVA CLASSES Architectural Overview Figure 2 1 shows the components that make up a JAXB implementation Schema E Generator Application Code Portable SER PARS JAXB annotated ge classes javax xml bind XMLiJava Customization Binding Declarations I Schema Compiler Annotation driven Object Binding Factory Framework Implementation Schema to Java _Javato Schema Figure 2 1 JAXB Architectural Overview A JAXB implementation consists of the following architectural components e schema compiler binds a source schema to a set of schema derived pro gram elements The binding is described by an XML based binding lan guage schema generator maps a set of existing program elements to a derived schema The mapping is described by program annotations binding runtime framework provides unmarshalling reading and mar shalling writing operations for accessing manipulating and validating XML content using either schema derived or existing program elements THE JAXB BINDING PROCESS The J AXB Binding Process Figure 2 2 shows what occurs
171. hat are exposed to web service clients must have JAX B compatible parameters and return types See Default Data Type Bindings page 6 The implementing class must not be declared final and must not be abstract The implementing class must have a default public constructor The implementing class must not define the finalize method The implementing class may use the javax annotation PostConstruct or javax annotation PreDestroy annotations on its methods for lifecy cle event callbacks The PostConstruct method is called by the container before the imple menting class begins responding to web service clients CODING THE SERVICE ENDPOINT IMPLEMENTATION CLASS xix The PreDestroy method is called by the container before the endpoint is removed from operation Coding the Service Endpoint Implementation Class In this example the implementation class He11o is annotated as a web service endpoint using the WebService annotation Hello declares a single method named sayHello annotated with the WebMethod annotation WebMethod exposes the annotated method to web service clients sayHel1o returns a greet ing to the client using the name passed to sayHello to compose the greeting The implementation class also must define a default public no argument con structor package helloservice endpoint import javax jws WebService wWebService public class Hello private String message new String Hello public void Hello
172. he WS I Basic Profile The follow ing code fragment retrieves the SOAPHeader object from message and adds a 134 SOAP WITH ATTACHMENTS API FOR JAVA new SOAPHeaderElement object to it This SOAPHeaderElement object contains the correct qualified name and attribute for a WS I conformance claim header SOAPHeader header message getSOAPHeader QName headerName new QName http ws i1 org schemas conformanceClaim Claim wsi SOAPHeaderElement headerElement header addHeaderElement headerName headerElement addAttribute new QNameC conformsTo http ws i1 org profi les basic 1 1 At this point header contains the SOAPHeaderElement object headerElement identified by the QName object headerName Note that the addHeaderElement method both creates headerElement and adds it to header A conformance claim header has no content This code produces the following XML header lt SOAP ENV Header gt lt wsi Claim xmIns wsi http ws i org schemas conformanceClaim conformsTo http ws i org profiles basic 1 1 gt lt SOAP ENV Header gt For more information about creating SOAP messages that conform to WS I see the Conformance Claim Attachment Mechanisms document described in the Conformance section of the WS I Basic Profile For a different kind of header you might want to add content to headerElement The following line of code uses the method addTextNode to do this headerElement addTextNodeC order
173. he following methods getitemsQ e setItems primer po Items value e getOrderDateQ e setOrderDate java util Calendar value e getComment e setComment java lang String value getBillToQ e setBillTo primer po USAddress value getShipToQ e setShipTo primer po USAddress value 28 USING JAXB The PurchaseOrderType java code looks like this package primer po public interface PurchaseOrderType primer po Items getItems void setItems primer po Items value java util Calendar getOrderDateQ void setOrderDate java util Calendar value java lang String getComment void setComment java lang String value primer po USAddress getBillToQ void setBillTo primer po USAddress value primer po USAddress getShipToQ void setShipTo primer po USAddress value USAddress java In USAddress java below The USAddress class is part of the primer po package Content in instantiations of this class bind to the XML schema element named USAddress USAddress is a public interface that provides the following methods getStateQ setState String value getZipQ setZip java math BigDecimal value getCountryQ setCountry String value getCityQ setCity String value getStreet setStreet String value getName setName String value The USAddress java code looks like this package primer po public interface USAddress String getState BASIC EXAMPLES 29 void
174. he path_name argument The attachments directory contains a file named addr txt that you can use asant run Dfile addr txt 168 SOAP WITH ATTACHMENTS API FOR JAVA When you run Attachments using this command line you will see output like the following Running Attachments Attachment attached_text has content type text plain Attachment contains Update address for Sunny Skies Inc to 10 Upbeat Street Pleasant Grove CA 95439 Attachment attached_image has content type image jpeg SOAPFaultlestjava The example SOAPFaultTest java based on the code fragments in the sections Creating and Populating a SOAPFault Object page 147 and Retrieving Fault Information page 149 creates a message that has a SOAPFault object It then retrieves the contents of the SOAPFau1t object and prints them You will find the code for SOAPFaultTest in the following directory lt INSTALL gt javaeetutorial5 examples saaj fault src Running SOAPFaulttest To run SOAPFaultTest you use the file build xml that is in the directory lt INSTALL gt javaeetutorial5 examples saaj fault Like HeaderExample this example contains code that allows you to generate either a SOAP 1 1 ora SOAP 1 2 message To run SOAPFaultTest use one of the following commands asant run Dsoap 1 1 asant run Dsoap 1 2 When you run SOAPFaultTest to generate a SOAP 1 1 message you will see output like the following line breaks have been inserted in the message for
175. how to retrieve the contents A SOAPFau1t object which is optional is added to the SOAPBody object to convey status or error information It must always have a fault code and a String explanation of the fault A SOAP Fault object must indicate the actor that is the source of the fault only when there are multiple actors otherwise it is optional Similarly the SOAPFault object must contain a Detail object with one or more DetailEntry objects only when the contents of the SOAPBody object could not be processed successfully See SOAPFaultTest java page 168 for an example that uses code like that shown in this section Code Examples The first part of this tutorial uses code fragments to walk you through the funda mentals of using the SAAJ APL In this section you will use some of those code fragments to create applications First you will see the program Request java Then you will see how to run the programs MyUddiPing java HeaderExam ple java DOMExample java DOMSrcExample java Attachments java and SOAPFaultTest java Note Before you run any of the examples follow the preliminary setup instructions in Building the Examples page xxxiii 152 SOAP WITH ATTACHMENTS API FOR JAVA Requestjava The class Request java puts together the code fragments used in the section Tutorial page 123 and adds what is needed to make it a complete example of a client sending a request response message In addition to putting all the code
176. ials The following code fragment shows how to do this String username testuser String password testuser Get authorization from the registry PasswordAuthentication passwdAuth new PasswordAuthentication username password toCharArray HashSet lt PasswordAuthentication gt creds new HashSet lt PasswordAuthentication gt creds add passwdAuth connection setCredentials creds Creating an Organization The client creates the organization and populates it with data before publishing it MANAGING REGISTRY DATA An Organization object is one of the more complex data items in the JAXR API It normally includes the following e A Name object e A Description object e A Key object representing the ID by which the organization is known to the registry This key is created by the registry not by the user and is returned after the organization is submitted to the registry e A PrimaryContact object which is a User object that refers to an autho rized user of the registry A User object normally includes a PersonName object and collections of TelephoneNumber EmailAddress and Postal Address objects e A collection of Classification objects e Service objects and their associated ServiceBinding objects For example the following code fragment creates an organization and specifies its name description and primary contact When a client creates an organization to be published to a UDDI registry it do
177. ication Server for Message Security page 243 To configure message security at the application level read Configuring Application Specific Message Security page 244 Configuring the Application Server for Message Securty The following steps briefly explain how to configure the Application Server for message security For more detailed information on configuring the Application Server for message security refer to the Application Server s Administration Guide For a link to this document see Further Information page 251 To configure the SOAP layer message security providers in the client and server side containers of the Application Server follow these steps 1 Start the Application Server as described in Starting and Stopping the Application Server page 28 2 Start the Admin Console as described in Starting the Admin Console page 29 In the Admin Console tree component expand the Configuration node Expand the Security node Expand the Message Security node Select the SOAP node Select the Message Security tab OND NM FW On the Edit Message Security Configuration page specify a provider to be used on the server side and or a provider to be used on the client side for all applications for which a specific provider has not been bound For more description of each of the fields on this page select Help from the Admin Console 9 Select Save 243 SECURING WEB SERVICES 10 To modify the mes
178. ication defines three such attributes role a new name for actor mustUnderstand and relay The next sections discuss these attributes See HeaderExample java page 160 for an example that uses the code shown in this section The Actor Atribute The actor attribute is optional but if it is used it must appear in a SOAPHeader Element object Its purpose is to indicate the recipient of a header element The default actor is the message s ultimate recipient that is if no actor attribute is supplied the message goes directly to the ultimate recipient An actor is an application that can both receive SOAP messages and forward them to the next actor The ability to specify one or more actors as intermediate recipients makes it possible to route a message to multiple recipients and to sup ply header information that applies specifically to each of the recipients For example suppose that a message is an incoming purchase order Its SOAP Header object might have SOAPHeaderElement objects with actor attributes that route the message to applications that function as the order desk the shipping desk the confirmation desk and the billing department Each of these applica tions will take the appropriate action remove the SOAPHeaderElement objects relevant to it and send the message on to the next actor Note Although the SAAJ API provides the API for adding these attributes it does not supply the API for processing them For example
179. ice specConcept setDescription s ExternalLink wsdlLink blcm createExternalLink http localhost 8080 hel lo jaxws hello WSDL Hello WSDL document specConcept addExternalLink wsd1Link Next you classify the Concept object as a WSDL document To do this for a UDDI registry you search the registry for the well known classification scheme uddi org types using its key ID The UDDI term for a classification scheme is Model Then you create a classification using the name and value wsd1 Spec Finally you add the classification to the concept String uuid_types uuid clacf26d 9672 4404 9d70 39b756e62ab4 ClassificationScheme uddiOrgTypes ClassificationScheme bqm getRegistryObject Cuuid_types LifeCycleManager CLASSIFICATION_SCHEME Classification wsd1SpecClassification blcm createClassification uddiOrgTypes wsdlSpec wsd1Spec specConcept addClassification wsd1SpecClassi fication Finally you save the concept using the saveConcepts method similarly to the way you save an organization Collection lt Concept gt concepts new ArrayList lt Concept gt Q concepts add specConcept BulkResponse concResponse blcm saveConcepts concepts After you have published the concept you normally add the concept for the WSDL document to a service binding To do this you can retrieve the key for the 192 JAVA API FOR XML REGISTRIES concept from the response returned by the saveConcepts method you us
180. igital signature ser vices The XML Digital Signature specification is defined by the W3C WS I SPECIFICATIONS This proposal is to define and incorporate the high level implementation independent Java APIs e JSR 106 XML Encryption APIs JSR 106 defines a standard set of APIs for XML digital encryption ser vices XML Encryption can be used to perform fine grained element based encryption of fragments within an XML Document as well as encrypt arbitrary binary data and include this within an XML document e JSR 155 Web Services Security Assertions JSR 155 provides a set of APIs exchange patterns and implementation to securely integrity and confidentiality exchange assertions between web services based on OASIS SAML e JSR 183 Web Services Message Security APIs JSR 183 defines a standard set of APIs for Web services message secu rity The goal of this JSR is to enable applications to construct secure SOAP message exchanges e JSR 196 Java Authentication Service Provider Interface for Containers The proposed specification will define a standard service provider inter face by which authentication mechanism providers may be integrated with containers Providers integrated through this interface will be used to establish the authentication identities used in container access decisions including those used by the container in invocations of components in other containers WS Specifications According to the Web Service
181. imilar code to add a classifica tion to a Service object MANAGING REGISTRY DATA Adding Services and Service Bindings to an Organization Most organizations add themselves to a registry in order to offer services so the JAXR API has facilities to add services and service bindings to an organization Like an Organization object a Service object has a name a description and a unique key that is generated by the registry when the service is registered It may also have classifications associated with it A service also commonly has service bindings which provide information about how to access the service A ServiceBinding object normally has a description an access URI and a specification link which provides the linkage between a service binding and a technical specification that describes how to use the ser vice by using the service binding The following code fragment shows how to create a collection of services add service bindings to a service and then add the services to the organization It specifies an access URI but not a specification link Because the access URI is not real and because JAXR by default checks for the validity of any published URI the binding sets its validateURI property to false Create services and service Collection lt Service gt services new ArrayList lt Service gt InternationalString s blcm createInternationalStringC My Service Name Service service blcm createService s s bl
182. implement the DOM Node and Element interfaces you have many options for adding or changing message content e Use only DOM APIs e Use only SAAJ APIs e Use SAAJ APIs and then switch to using DOM APIs e Use DOM APIs and then switch to using SAAJ APIs The first three of these cause no problems After you have created a message whether or not you have imported its content from another document you can start adding or changing nodes using either SAAJ or DOM APIs But if you use DOM APIs and then switch to using SAAJ APIs to manipulate the document any references to objects within the tree that were obtained using DOM APIs are no longer valid If you must use SAAJ APIs after using DOM APIs you should set all your DOM typed references to null because they can become invalid For more information about the exact cases in which references become invalid see the SAAJ API documentation The basic rule is that you can continue manipulating the message content using SAAJ APIs as long as you want to but after you start manipulating it using DOM you should no longer use SAAJ APIs ADDING ATTACHMENTS Adding Attachments An AttachmentPart object can contain any type of content including XML And because the SOAP part can contain only XML content you must use an AttachmentPart object for any content that is not in XML format Creating an AttachmentPart Objectand Adding Content The SOAPMessage object creates an AttachmentPart object and
183. in primer po JAXBContext jc JAXBContext newInstance primer po An Unmarshal ler instance is created Unmarshaller u jc createUnmarshallerQ po xml is unmarshalled into a Java content tree comprising objects gener ated by the JAXB binding compiler into the primer po package PurchaseOrder po PurchaseOrder u unmarshal new FileInputStream po xml A simple string is printed to system out to provide a heading for the pur chase order invoice System out printIn Ship the following items to get and display methods are used to parse XML content in preparation for output USAddress address po getShipTo displayAddress address Items items po getItems displayItems items Basic error handling is implemented catch JAXBException je je printStackTraceQ catch IOException ioe joe printStackTraceQ The USAddress branch of the Java tree is walked and address information is printed to system out public static void displayAddress USAddress address display the address System out printIn t address getNameQ System out printIn t address getStreetQ System out printIn t address getCityQ address getState address getZipQ System out printIn t address getCountry Q n MODIFY MARSHAL EXAMPLE 31 9 The Items list branch is walked and item information is printed to sys
184. in Table 3 5 Table 3 5 schemagen Command Line Options Option or Argument Description Specifies the location of the processor and javac generated class sdapath files ABOUT THE SCHEMA TO JAVA BINDINGS 19 About the Schema to ava Bindings When you run the JAXB binding compiler against the po xsd XML schema used in the basic examples Unmarshal Read Modify Marshal Unmarshal Vali date the JAXB binding compiler generates a Java package named primer po containing eleven classes making a total of twelve classes in each of the basic examples Table 3 6 Schema Derived JAXB Classes in the Basic Examples jets Peseriotlom OOO primer po Comment java Public interface extending javax xml1 bind E lement binds to the global schema element named comment Note that JAXB generates element interfaces for all global element declarations primer po Items java Public interface that binds to the schema complexType named Items primer po ObjectFactory java Public class extending com sun xm1 bind DefaultJAXB ContextImp1 used to create instances of specified inter faces For example the ObjectFactory createComment method instantiates a Comment object primer po PurchaseOrder java Public interface extending javax xml1 bind Element and PurchaseOrderType binds to the global schema element named PurchaseOrder primer po PurchaseOrderType java Public interface that binds to the schema compl
185. in the Application Server Tables 6 1 and 6 2 list and describe these properties Table 6 1 Standard JAXR Connection Properties Property Name and Description Default Value javax xml registry queryManagerURL Specifies the URL of the query manager service within the target registry provider javax xml registry 1ifeCycleManagerURL Same as the specified queryManagerURL Specifies the URL of the life cycle manager service value within the target registry provider for registry updates ESTABLISHING A CONNECTION 179 Table 6 1 Standard JAXR Connection Properties Continued Property Name and Description Default Value javax xml registry semanticEquivalences Specifies semantic equivalences of concepts as one or more tuples of the ID values of two equivalent concepts separated by a comma The tuples are separated by ver tical bars jid1 id2 id3 id4 javax xml registry security authentica tionMethod None UDDI_GET_AUTHTOKEN Provides a hint to the JAXR provider on the authentica is the only supported tion method to be used for authenticating with the regis value try provider javax xml registry uddi maxRows The maximum number of rows to be returned by find operations Specific to UDDI providers javax xml registry postalAddressScheme The ID of a Classi ficationScheme to be used as the default postal address scheme See Specifying Postal Addresses page 197 for an example Table 6 2 Imp
186. indClassi ficationSchemeByName method 188 findConcepts method 184 findOrganization method 182 framework XWS Security 247 fully qualified names 127 G getAttachments method 139 getBody method 126 getEnvelope method 126 getHeader method 126 getRegistryObject method 183 getSOAPBody method 126 INDEX 255 getSOAPHeader method 126 getSOAPPart method 126 getValue method 132 H HTTP xv xvi setting proxies 179 I information model JAXR 172 173 ISO 3166 country codes 181 J Java EE applications JAXR example 206 javax activation DataHandler class 137 138 javax xml l namespace QName class 127 javax xml registry package 173 javax xml registry infomodel package 173 javax xml registry 1ifeCycleM anagerURL connection property 178 javax xml registry postalAd dressScheme connection property 179 197 javax xml registry queryMan agerURL connection property 178 javax xml registry securi ty authenticationMethod connec tion property 179 javax xml registry seman 256 INDEX ticEquivalences connection prop erty 179 197 javax xml registry ud di maxRows connection property 179 javax xm1 soap package 117 javax xml transform Source in terface 135 JAXM specification 118 JAXR 171 adding classifications 188 service bindings 189 services 189 architecture 173 capability levels 172 clients 173 174 creating connections 177 defining taxonomies 194 definition 172 establishing security creden tials 186 finding
187. inding declarations in an XML schema file take the form of lt xsd appinfo gt elements embedded in schema lt xsd annotation gt elements xsd is the XML schema namespace pre fix as defined in W3C XML Schema Part 1 Structures The general form for inline customizations is shown below lt xS annotation gt lt xs appinfo gt binding declarations lt xs appinfo gt lt xsiannotation gt Customizations are applied at the location at which they are declared in the schema For example a declaration at the level of a particular element would apply to that element only Note that the XMLSchema namespace prefix must be used with the lt annotation gt and lt appinfo gt declaration tags In the example above xs is used as the namespace prefix so the declarations are tagged lt xS annotation gt and lt xs appinfo gt 37 38 USING JAXB Extemal Binding Customization Files Customizations to JAXB bindings made by means of an external file containing binding declarations take the general form shown below lt jxb bindings schemaLocation xs anyURI gt lt jxb bindings node xs string gt lt binding declaration gt lt jxb bindings gt lt jxb bindings gt e schemaLocation is a URI reference to the remote schema e node is an XPath 1 0 expression that identifies the schema node within schemaLocation to which the given binding declaration is associated For example the first schemaLocation node declaration in a
188. inelItems body addBodyE lement bodyName QName childName new QNameC Order SOAPElement order purchaseLinelItems addChi 1dElement chi 1dName childName new QName Product SOAPElement product order addChi1ldElement chi 1dName product addTextNodeC Apple childName new QNameC Price SOAPElement price order addChi1ldElement chi ldName price addTextNode 1 56 childName new QNameC Order SOAPElement order2 purchaseLineltems addChi 1dE1ement chi 1dName childName new QName Product SOAPElement product2 order2 addChi1ldElement chi 1ldName CREATING AND SENDING A SIMPLE MESSAGE 131 product2 addTextNode Peach childName soapFactory new QName Price SOAPElement price2 order2 addChi 1dElement chi ldName price2 addTextNode 1 48 The SAAJ code in the preceding example produces the following XML in the SOAP body lt PO PurchaseLineItems xmIns PO0 http sonata fruitsgalore com gt lt Order gt lt Product gt App 1e lt Product gt lt Price gt 1 56 lt Price gt lt Order gt lt Order gt lt Product gt Peach lt Product gt lt Price gt 1 48 lt Price gt lt Order gt lt PO PurchaseLineItems gt Getting a SOAPC onnection Object The SAAJ API is focused primarily on reading and writing messages After you have written a message you can send it using various mechanisms such as JMS or JAXM The SAAJ API does however provide a simple mecha
189. ing ValueType Java class that provides an XML representation of the data It is the object that is used for marshalling and unmarshalling BoundType Java class that is used to process XML content public abstract class XmlAdapter lt ValueType BoundType gt Do nothing constructor for the derived classes protected XmlAdapter Convert a value type to a bound type public abstract BoundType unmarshal ValueType v Convert a bound type to a value type public abstract ValueType marshal BoundType v You can use the XmlJavaTypeAdapter annotation to associate a particular XmlAdapter implementation with a Target type PACKAGE FIELD METHOD TYPE or PARAMETER The j2s xmlAdapter field example demonstrates an XmlAdapter for mapping XML content into and out of a custom HashMap The HashMap object basket cor 29 in class KitchenWorldBasket uses a key of type int and a value of type String We want these datatypes to be reflected in the XML content that is read and written The XML content should look like this lt basket gt lt entry key 9027 gt glasstop stove in black lt entry gt lt entry key 288 gt wooden spoon lt entry gt lt basket gt The default schema generated for Java type HashMap does not reflect the desired format lt xs element name basket gt lt xs complexType gt lt xsS Sequence gt lt xs element name entry minOccurs 0 maxOccurs unbounde
190. ing Name objects the SOAPFactory class provides methods for creating Detail objects and SOAP fragments You will find an explanation of Detail objects in Overview of SOAP Faults page 146 and Creating and Populating a SOAPFault Object page 147 QName objects associated with SOAPBodyElement or SOAPHeaderElement objects must be fully qualified that is they must be created with a namespace URI a local part and a namespace prefix Specifying a namespace for an ele ment makes clear which one is meant if more than one element has the same local name The following code fragment retrieves the SOAPBody object body from message constructs a QName object for the element to be added and adds a new SOAP BodyElement object to body SOAPBody body message getSOAPBody QName bodyName new QNameC http wombat ztrade com GetLastTradePrice m SOAPBodyElement bodyElement body addBodyE1ement bodyName At this point body contains a SOAPBodyElement object identified by the QName object bodyName but there is still no content in bodyElement Assuming that 127 128 SOAP WITH ATTACHMENTS API FOR JAVA you want to get a quote for the stock of Sun Microsystems Inc you need to cre ate a child element for the symbol using the addChildElement method Then you need to give it the stock symbol using the addTextNode method The QName object for the new SOAPElement object symbol is initialized with only a local name because child
191. ing code to display the values of all the header elements Iterator allHeaders header examineAl lHeaderElements while allHeaders hasNextQ SOAPHeaderElement headerElement CSOAPHeaderElement al 1lHeaders next Q QName headerName headerElement getE lementQName System out printInC nHeader name is headerName toString System out printInC Actor is headerElement getActor The role Attribute The role attribute is the name used by the SOAP 1 2 specification for the SOAP 1 2 actor attribute The SOAPHeaderElement methods setRole and getRole perform the same functions as the setActor and getActor methods 143 144 SOAP WITH ATTACHMENTS API FOR JAVA The mustUnderstand Attibute The other attribute that must be added only to a SOAPHeaderElement object is mustUnderstand This attribute says whether or not the recipient indicated by the actor attribute is required to process a header entry When the value of the mustUnderstand attribute is true the actor must understand the semantics of the header entry and must process it correctly to those semantics If the value is false processing the header entry is optional A SOAPHeaderElement object with no mustUnderstand attribute is equivalent to one with a mustUnderstand attribute whose value is false The mustUnderstand attribute is used to call attention to the fact that the seman tics in an element are different from the semantics in its parent or peer element
192. ining DOMExample DOMExample first creates a DOM document by parsing an XML document The file it parses is one that you specify on the command line static Document document DocumentBuilderFactory factory DocumentBui lderFactory newInstanceQ factory setNamespaceAware true try DocumentBuilder builder factory newDocumentBuilder document builder parse new File args Next the example creates a SOAP message in the usual way Then it adds the document to the message body SOAPBodyElement docElement body addDocument document This example does not change the content of the message Instead it displays the message content and then uses a recursive method getContents to traverse the element tree using SAAJ APIs and display the message contents in a readable form public void getContents Iterator iterator String indent while iterator hasNextQ Node node Node iterator nextQ SOAPElement element null Text text null if node instanceof SOAPElement element CSOAPElement node QName name element getElementQName System out printInCindent Name is name toString Iterator attrs element getAl lAttributesAsQNames while Cattrs hasNextQ QName attrName QName attrs nextQ System out printInCindent attrName toStringQ System out printInCindent Attribute value is element getAttributeValueCattrName Attribute name is Iterator iter2 element g
193. ion and decryption for other mechanisms the keys used for encryp tion and decryption are different Authentication is as fundamentally a part of our lives as privacy We use authen tication throughout our everyday lives when we sign our name to some docu ment for instance and as we move to a world where our decisions and agreements are communicated electronically we need to have electronic tech niques for providing authentication The crypt in encryption and decryption is cryptography Cryptography pro vides mechanisms for providing authentication which include encryption and decryption as well as digital signatures and digital timestamps A digital signa ture binds a document to the possessor of a particular key while a digital times tamp binds a document to its creation at a particular time These cryptographic mechanisms can be used to control access to a shared disk drive a high security installation or a pay per view TV channel Authentication is any process through which one proves and verifies certain information Sometimes one may want to verify the origin of a document the identity of the sender the time and date a document was sent and or signed the identity of a computer or user and so on A digital signature is a cryptographic 236 SECURING WEB SERVICES means through which many of these may be verified The digital signature of a document is a piece of information based on both the document and the sign
194. ion status sv We can also iterate over the references and check the validation status of each one as follows Iterator i signature getSignedInfo getReferencesQ iteratorQ for int j 0 i hasNextQ j boolean refValid Reference VALIDATE EXAMPLE i nextQ validate valContext System out printInC ref j validity status refValid Using KeySelectors KeySelectors are used to find and select keys that are needed to validate an XMLSignature Earlier when we created a DOMValidateContext object we passed a KeySelector object as the first argument DOMValidateContext valContext new DOMValidateContext new KeyValueKeySelector Q nl item Q Alternatively we could have passed a PublicKey as the first argument if we already knew what key is needed to validate the signature However we often don t know The KeyValueKeySelector is a concrete implementation of the abstract KeySe lector class The KeyValueKeySelector implementation tries to find an appropriate validation key using the data contained in KeyValue elements of the KeyInfo element of an XMLSignature It does not determine if the key is trusted This is a very simple KeySelector implementation designed for illustration rather than real world usage A more practical example of a KeySelector is one that searches a KeyStore for trusted keys that match X5 9Data information for example X509SubjectName X509IssuerSerial X509SKI or X509Certi
195. is registry follow the instructions in Preliminaries Getting Access to a Registry page 175 If the Application Server where you install the registry is running on a remote system open uddi properties in a text editor and replace localhost with the name of the remote system The prepare target creates a directory named build To invoke the prepare tar get you type the following at the command line asant prepare The target named build compiles the source file MyUddiPing java and puts the resulting class file in the build directory So to do these tasks you type the following at the command line asant build Examining MyUddiPing We will go through the file MyUddiPing java a few lines at a time concentrat ing on the last section This is the part of the application that accesses only the content you want from the XML message returned by the UDDI registry The first lines of code import the interfaces used in the application import javax xml soap SOAPConnectionFactory import javax xml soap SOAPConnection import javax xml soap MessageFactory import javax xml soap SOAPMessage import javax xml soap SOAPHeader import javax xml soap SOAPBody import javax xml soap SOAPBodyElement import javax xml soap SOAPElement import javax xml namespace QName import java net URL import java util Properties import java util Enumeration import java util Iterator import java io FileInputStream MYUDDIPING JAVA 155 The n
196. ish url http localhost 8080 RegistryServer link uri http localhost 8080 hel1lo jaxws hel1lo WSDL wsdlorg svcbnd uri http localhost 8080 hel 1lo jaxws hello Specify the fully qualified host name instead of localhost or change 8080 to the correct value for your system 2 Optional Edit the following lines which contain empty strings for the proxy hosts to specify your own proxy settings The proxy host is the sys tem on your network through which you access the Internet you usually specify it in your Internet browser settings HTTP and HTTPS proxy host and port http proxyHost COMPILING THE EXAMPLES http proxyPort 8080 https proxyHost https proxyPort 8080 The proxy ports have the value 8080 which is the usual one change this string if your proxy uses a different port Your entries usually follow this pattern http proxyHost proxyhost mydomain http proxyPort 8080 https proxyHost proxyhost mydomain https proxyPort 8080 You need to specify a proxy only if you want to specify an external link or service binding that is outside your firewall 3 Feel free to change any of the organization data in the remainder of the file This data is used by the publishing and postal address examples Try to make the organization names unusual so that queries will return relatively few results You can edit the src JAXRExamples properties file at any time The asant targets that run the client examples will use the la
197. it is legal in the XML schema lan guage it cannot be used as a name for a schema derived class generated by JAXB When this schema is run against the JAXB binding compiler with the ant fail command the following error message is returned xjc ERROR Attempt to create a property having the same name as the reserved word Class xjc line 6 of example xsd The second conflict is that there are an element and a complexType that both use the name Foobar lt xs element name FooBar type FooBar gt lt xs complexType name FooBar gt In this case the error messages returned are xjc ERROR A property with the same name Zip is generated from more than one schema component xjc line 22 of example xsd xjc ERROR Relevant to above error another one is generated from this schema component xjc line 20 of example xsd The third conflict is that there are an element and an attribute both named zip lt xs element name zip type xs integer gt lt xs attribute name zip type xs string gt 62 USING JAXB The error messages returned here are xjc ERROR A property with the same name Zip is generated from more than one schema component xjc line 22 of example xsd xjc ERROR Relevant to above error another one is generated from this schema component xjc line 20 of example xsd Output Fom Running the ant Task Without Using a Binding Declarations File Here
198. ization gt orgs add org BulkResponse response blcm saveOrganizations orgs Collection exceptions response getException if exceptions null System out printInC Organization saved Collection keys response getCollection Iterator keyIter keys iterator if keyIter hasNextQ Key orgKey Key keyIter nextQ String id orgKey getIdQ System out printInC Organization key is id Publishing a Specification Concept A service binding can have a technical specification that describes how to access the service An example of such a specification is a WSDL document To publish the location of a service s specification if the specification is a WSDL docu ment you create a Concept object and then add the URL of the WSDL docu ment to the Concept object as an ExternalLink object The following code fragment shows how to create a concept for the WSDL document associated with the simple web service example in Creating a Simple Web Service and Cli MANAGING REGISTRY DATA 191 ent with JAX WS page xvi First you call the createConcept method to cre ate a concept named Hel loConcept After setting the description of the concept you create an external link to the URL of the Hello service s WSDL document and then add the external link to the concept Concept specConcept blcm createConcept null HelloConcept InternationalString s blcm createInternationalString Concept for Hello Serv
199. l the examples are specified in the files lt INSTALL gt jwstutoriall3javaeetutorial5 examples com mon bui Id properties and lt INSTALL gt jwstutorial1l3javaeetutorial5 examples com mon targets xml1 Build properties and targets common to a particular technol ogy are specified in the files lt INSTALL gt jwstutoriall3javaeetutorial5 exam ples tech common bui ld properties and lt INSTALL gt jwstutoriall3javaeetutorial5 exam ples tech common targets xm xi xii ABOUT THIS TUTORIAL To run the asant scripts you must set common build properties in the file lt INSTALL gt javaeetutorial5 examples common build properties as fol lows e Set the javaee home property to the location of your Application Server installation The build process uses the javaee home property to include the libraries in lt JAVAEE_HOME gt 1ib in the classpath All examples that run on the Application Server include the Java EE library archive lt JAVAEE_HOME gt 1ib javaee jar in the build classpath Some exam ples use additional libraries in lt JAVAEE_HOME gt 1ib the required librar ies are enumerated in the individual technology chapters lt JAVAEE_HOME gt refers to the directory where you have installed the Application Server Note On Windows you must escape any backslashes in the javaee home property with another backslash or use forward slashes as a path separator So if your Appli cation Server installation is C Sun AppServer y
200. l through a stub a local object that acts as a proxy for the remote service The stub is created at development time by the wsimport tool which generates JAX WS portable artifacts based on a WSDL file Coding the Client When invoking the remote methods on the stub the client performs these steps 1 Uses the javax xml1 ws WebServiceRef annotation to declare a reference to a web service WebServiceRef uses the wsd1Location element to spec ify the URI of the deployed service s WSDL file xxii BUILDING WEB SERVICES WITH JAX WS WebServiceRef wsdlLocation http localhost 8080 hel loservice hel1lo wsd1 static HelloService service Retrieves a proxy to the service also known as a port by invoking getH elloPort on the service Hello port service getHelloPortQ The port implements the SEI defined by the service Invokes the port s sayHello method passing to the service a name String response port sayHello name the full source of HelloClient located in the lt INSTALL gt javaeetutorial5 examples jaxws simpleclient src direc package simpleclient import javax xml ws WebServiceRef import helloservice endpoint HelloService import helloservice endpoint Hello public class HelloClient WebServiceRef wsdlLocation http localhost 8080 hel loservice hel lo wsd1 static HelloService service public static void main String args try HelloClient client new HelloClientQ clien
201. lementation Specific JAXR Connection Properties Property Name and Description Default Value com sun xml registry http proxyHost Specifies the HTTP proxy host to be used for access ing external registries com sun xml registry http proxyPort Specifies the HTTP proxy port to be used for access ing external registries usually 8080 180 JAVA API FOR XML REGISTRIES Table 6 2 Implementation Specific JAXR Connection Properties Continued Property Name and Description com sun xml registry https proxyHost Specifies the HTTPS proxy host to be used for accessing external registries Default Value Same as HTTP proxy host value com sun xml registry https proxyPort Specifies the HTTPS proxy port to be used for accessing external registries usually 8080 Same as HTTP proxy port value com sun xml registry http proxyUserName Specifies the user name for the proxy host for HTTP proxy authentication if one is required com sun xml registry http proxyPassword Specifies the password for the proxy host for HTTP proxy authentication if one is required com sun xml registry useCache Boolean Tells the JAXR implementation to look for registry passed in objects in the cache first and then to look in the regis as String try if not found com sun xml registry userTaxonomyFi le names For details on setting this property see Defining a Taxonomy page 194 Obtaining and Using a R
202. lt xs choice gt lt xs group gt lt xs schema gt Customizing a choice Model Group The lt INSTALL gt examples jaxb bind choice binding xjb binding declara tions file demonstrates one way to override the default derived names for choice BIND CHOICE EXAMPLE 65 model groups in example xsd by means of a lt jxb globalBindings gt declara tion lt jxb bindings schemaLocation example xsd node xs schema gt lt jxb globalBindings bindingStyle modelGroupBinding gt lt jxb schemaBindings gt lt jxb package name example gt lt jxb schemaBindings gt lt jxb bindings lt jxb bindings gt This customization results in the choice model group being bound to its own content interface For example given the following choice model group lt xS group name ModelGroupChoice gt lt xs choice gt lt xs element name bool type xs boolean gt lt xs element name comment type xs string gt lt xs element name value type xs int gt lt xs choice gt lt xXS i group gt the globalBindings customization shown above causes JAXB to generate the following Java class Java content class for model group public interface ModelGroupChoice int getValue void setValue int value boolean isSetValue java lang String getComment void setComment java lang String value boolean isSetComment boolean isBool void setBool boolean value boolea
203. mService class allows you to develop and plug in an implementation of a specific transform or canonicalization algorithm for a par ticular XML mechanism type The TransformService class uses the standard JCA provider model for registering and loading implementations Each JSR 105 implementation should use the TransformService class to find a provider that supports transform and canonicalization algorithms in XML Signatures that it is generating or validating 218 JAVA XML DIGITAL SIGNATURE API Intoduction to XML Signatures As mentioned an XML Signature can be used to sign any arbitrary data whether it is XML or binary The data is identified via URIs in one or more Reference elements XML Signatures are described in one or more of three forms detached enveloping or enveloped A detached signature is over data that is external or outside of the signature element itself Enveloping signatures are sig natures over data that is inside the signature element and an enveloped signature is a signature that is contained inside the data that it is signing Example of an XML Signature The easiest way to describe the contents of an XML Signature is to show an actual sample and describe each component in more detail The following is an example of an enveloped XML Signature generated over the contents of an XML document The contents of the document before it is signed are lt Envelope xmlns urn envelope gt lt Envelope gt The resulting
204. maps a JavaBean s properties and fields to an XML Schema type The class elements are mapped to either an XML Schema complex type or an XML Schema simple type The default element order for a generated schema type is currently unspecified because Java reflection does not impose a return order The lack of reliable element ordering negatively impacts application port ability You can use two annotations XmlAccessorOrder and XmlType pro J2S XMLA CCESSORORDER EXAMPLE pOrder to define schema element ordering for applications that need to be portable across JAXB Providers The XmlAccessorOrder annotation imposes one of two element ordering algo rithms AccessorOrder UNDEFINED or AccessorOrder ALPHABETICAL AccessorOrder UNDEFINED is the default setting The order is dependent on the system s reflection implementation AccessorOrder ALPHABETICAL orders the elements in lexicographic order as determined by java lang String CompareTo String anotherString You can define the XmlAccessorOrder annotation for annotation type Ele mentType PACKAGE on a class object When the XmlAccessorOrder anno tation is defined on a package the scope of the formatting rule is active for every class in the package When defined on a class the rule is active on the contents of that class There can be multiple XmlAccessorOrder annotations within a package The order of precedence is the innermost class annotation takes precedence over the outer an
205. marshalException CUSTOMIZING JAXB BINDINGS Customizing J AXB Bindings The remainder of this chapter describes several examples that build on the con cepts demonstrated in the basic examples The goal of this section is to illustrate how to customize JAXB bindings by means of custom binding declarations made in either of two ways e As annotations made inline in an XML schema e As statements in an external file passed to the JAXB binding compiler Unlike the examples in Basic Examples page 29 which focus on the Java code in the respective Main java class files the examples here focus on customiza tions made to the XML schema before generating the schema derived Java bind ing classes Note Although JAXB binding customizations must currently be made by hand it is envisioned that a tool wizard may eventually be written by Sun or a third party to make this process more automatic and easier in general One of the goals of the JAXB technology is to standardize the format of binding declarations thereby mak ing it possible to create customization tools and to provide a standard interchange format between JAXB implementations This section just begins to scratch the surface of customizations you can make to JAXB bindings and validation methods For more information please refer to the JAXB Specification http java sun com xm1 downloads jaxb htm1 Why Customize In most cases the default bindings generated by the JAXB
206. ment Table 3 2 briefly describes the Customize examples Table 3 2 Customize JAXB Examples Customize Inline Exam Demonstrates how to customize the default JAXB bindings by ple using inline annotations in an XML schema Similar to the Customize Inline example this example illustrates alternate more terse bindings of XML simpleType definitions to Java datatypes Datatype Converter Example Illustrates how to use an external binding declarations file to pass binding customizations for a read only schema to the JAXB bind ing compiler External Customize Example Illustrates how to use customizations to resolve name conflicts reported by the JAXB binding compiler You should first move binding xjb the binding file out of the application directory to Fix Collides Example see the errors reported by the JAXB binding compiler and then look at binding xjb to see how the errors were resolved Run ning asant alone uses the binding customizations to resolve the name conflicts while compiling the schema 14 USING JAXB Table 3 3 briefly describes the Java to Schema examples Table 3 3 Java toSchema JAXB Examples Illustrates how to marshal and unmarshal JAXB annotated classes to XML schema The example also shows how to enable JAXP 1 3 validation at unmarshal time using a schema file that was gen erated from the JAXB mapped classes j2s create marshal Illustrates how to use the XmlAccessorOrder and
207. mentation The Java Web Services Developer Pack Java WSDP includes XML and Web Services Security XWSS a framework for securing JAX RPC JAX WS and SAAJ applications and message attachments XWS Security includes the following features e Support for securing JAX RPC and JAX WS applications at the service port and operation levels e XWS Security APIs for securing both JAX RPC and JAX WS applica tions and stand alone applications that make use of SAAJ APIs only for their SOAP messaging e A sample security framework within which a JAX RPC application devel oper will be able to secure applications by signing verifying encrypting and or decrypting parts of SOAP messages and attachments The message sender can also make claims about the security properties by associating security tokens with the message An example of a security 247 248 SECURING WEB SERVICES claim is the identity of the sender identified by a user name and pass word e Support for SAML Tokens and the WSS SAML Token Profile partial e Support for securing attachments based on the WSS SwA Profile Draft e Partial support for sending and receiving WS I Basic Security Profile BSP 1 0 compliant messages e Sample programs that demonstrate using the framework e Command line tools that provide specialized utilities for keystore manage ment including pkcs12import and keyexport XWSS supports deployment onto any of the following containers e Su
208. ments unnec essary to the client can be ignored and it can support XML views of non XML data StAX Use Cases The StAX specification defines a number of uses cases for the API e Data binding e Unmarshalling an XML document e Marshalling an XML document e Parallel document processing e Wireless communication e SOAP message processing e Parsing simple predictable structures e Parsing graph representations with forward references 79 80 STREAMING API FOR XML e Parsing WSDL e Virtual data sources e Viewing as XML data stored in databases e Viewing data in Java objects created by XML data binding e Navigating a DOM tree as a stream of events e Parsing specific XML vocabularies e Pipelined XML processing A complete discussion of all these use cases is beyond the scope of this chapter Please refer to the StAX specification for further information Comparing StAX to Other J AXP APIs As an API in the JAXP family StAX can be compared among other APIs to SAX TrAX and JDOM Of the latter two StAX is not as powerful or flexible as TrAX or JDOM but neither does it require as much memory or processor load to be useful and StAX can in many cases outperform the DOM based APIs The same arguments outlined above weighing the cost benefits of the DOM model versus the streaming model apply here With this in mind the closest comparisons between can be made between StAX and SAX and it is here that StAX offers feature
209. messageFactory MessageFactory newInstance SOAPMessage message messageFactory createMessage 156 SOAP WITH ATTACHMENTS API FOR JAVA The next lines of code retrieve the SOAPHeader and SOAPBody objects from the message and remove the header SOAPHeader header message getSOAPHeader header detachNode SOAPBody body message getSOAPBody The following lines of code create the UDDI find_business message The first line creates a SOAPBodyElement with a fully qualified name including the required namespace for a UDDI version 2 message The next lines add two attributes to the new element the required attribute generic with the UDDI ver sion number 2 0 and the optional attribute maxRows with the value 100 Then the code adds a child element that has the QName object name and adds text to the element by using the method addTextNode The added text is the business name you will supply at the command line when you run the application SOAPBodyElement findBusiness body addBodyElement new QName urn uddi org api_v2 find_business findBusiness addAttribute new QNameC generic 2 0 findBusiness addAttributeCnew QNameC maxRows 100 SOAPElement businessName findBusiness addChildElement new QName name businessName addTextNode args 1 The next line of code saves the changes that have been made to the message This method will be called automatically when the message is sent but it does
210. might send a SOAP fault is an intermediate recipient or actor As stated in the section Adding Attributes page 139 an actor that can not process a header that has a mustUnderstand attribute with a value of true must return a SOAP fault to the sender A SOAPFau1t object contains the following elements e A fault code Always required The fault code must be a fully qualified name it must contain a prefix followed by a local name The SOAP spec ifications define a set of fault code local name values which a developer can extend to cover other problems These are defined in section 4 4 1 of the SOAP 1 1 specification and in section 5 4 6 of the SOAP 1 2 specifica USING SOAP FAULTS tion Table 5 1 on page 149 lists and describes the default fault code local names defined in the specifications A SOAP 1 2 fault code can optionally have a hierarchy of one or more subcodes e A fault string Always required A human readable explanation of the fault e A fault actor Required if the SOAPHeader object contains one or more actor attributes optional if no actors are specified meaning that the only actor is the ultimate destination The fault actor which is specified as a URI identifies who caused the fault For an explanation of what an actor is see The Actor Attribute page 141 e A Detail object Required if the fault is an error related to the SOAPBody object If for example the fault code is Client indicating that the mes
211. mmunityprocess maintenance jsr109 index html e OASIS Standard 200401 Web Services Security SOAP Message Security 1 0 252 SECURING WEB SERVICES http docs oasis open org wss 2004 01 oasis 200401 wss soap message security 1 0 pdf XML Encryption Syntax and Processing http www w3 org TR xmlenc core Digital Signatures Working Draft http www w3 org Signature JSR 105 XML Digital Signature APIs http www jcp org en jsr detai1 id 105 JSR 106 XML Digital Encryption APIs http www jcp org en jsr detai1 id 106 Public Key Cryptography Standards PKCS http www rsasecurity com rsalabs pkcs index htm Java Authentication and Authorization Service JAAS http java sun com products jaas WS I Basic Security Profile Version 1 0 http ww ws 7i org Profi les BasicSecurityProfi le 1 0 2005 Q1 20 htm Web Services Security SOAP Messages with Attachments SwA Profile 1 0 http www oasis open org committees download php 10090 wss Swa profi le 1 0 draft 14 pdf Web Services Security SOAP Messages with Attachments SwA Profile 1 0 Interop 1 Scenarios http lists oasis open org archives wss 200410 pdf00003 pdf Web Services Security Security Assertion Markup Language SAML Token Profile 1 0 http docs oasis open org wss oasis wss saml token pro file 1 0 pdf Web Services Security Security Assertion Markup Language SAML Interop Scenarios http www oasis open org apps org workgroup wss
212. mple Java applications that are included in the lt javaee tutorial home gt examples jaxb directory These examples demonstrate and build upon key JAXB features and concepts It is rec ommended that you follow these procedures in the order presented After reading this chapter you should feel comfortable enough with JAXB that you can e Generate JAXB Java classes from an XML schema e Use schema derived JAXB classes to unmarshal and marshal XML con tent in a Java application e Create a Java content tree from scratch using schema derived JAXB classes e Validate XML content during unmarshalling and at runtime e Customize JAXB schema to Java bindings The primary goals of the Basic examples are to highlight the core set of JAXB functions using default settings and bindings After familiarizing yourself with these core features and functions you may wish to continue with Customizing JAXB Bindings page 35 for instructions on using Customize examples that demonstrate how to modify the default JAXB bindings Finally the Java to Schema examples show how to use annotations to map Java classes to XML schema 11 12 USING JAXB Note The Purchase Order schema po xsd and the Purchase Order XML file po xm1 used in the Basic and Customize samples are derived from the W3C XML Schema Part 0 Primer http www w3 org TR xmlschema Q edited by David C Fallside General Usage Instructions This section provides general usa
213. mplementing the Steamfilter Class The MyStreamFilter implements javax xml stream StreamFilter public class MyStreamFilter implements javax xml stream StreamFi lter Creating an Input Factory The next step is to create an instance of XMLInputFactory In this case various properties are also set on the factory XMLInputFactory xmlif null try xmlif XMLInputFactory newInstanceQ xmlif setProperty XMLInputFactory IS_REPLACING_ENTITY_REFERENC ES Boolean TRUE xmlif setProperty XMLInputFactory IS_SUPPORTING_EXTERNAL_ENTIT IES Boolean FALSE xmlif setProperty XMLInputFactory IS_NAMESPACE_AWARE Boolean TRUE xmlif setProperty XMLInputFactory IS_COALESCING Boolean TRUE scatch Exception ex ex printStackTraceQ System out printInC FACTORY xmlif System out printInC filename filename 110 STREAMING API FOR XML Creating the Filter The next step is to instantiate a file input stream and create the stream filter FileInputStream fis new FileInputStream filename XMLStreamReader xmlr xmlif createFi lteredReader xmlif createXMLStreamReader fis new MyStreamFilter int eventType xmIr getEventTypeQ printEventType eventType whi le xmIr hasNextQ eventType xmIr nextQ printEventType eventType printName xm1r eventType printText xml1r if xmlr isStartElementQ printAttributes xmlr printPIData xmlr System out printIn my
214. mplete file that uses this code look at the 250 SECURING WEB SERVICES example client in the jaxws2 simple doclit src simple client directory put the security config info BindingProvider stub getRequestContext put XwWSSecurityConfiguration MESSAGE_SECURITY_CONFIGURATION config 4 Invoke the method on the stub as you would if you were writing the client without regard to adding XWS Security The example for the application from the jaxws2 simple doclit src simple client directory is as shown below Holder lt String gt hold new HolderC Hello stub ping ticket hold To add message security to an existing JAX RPC JAX WS or SAAJ application using XWSS follow these steps on the server side 1 Create a server security configuration file and give it the name serviceName _ security_config xm An example of a server security configuration file can be found in the jaxws2 simple doclit etc server_security_config xml direc tory 2 No other changes need to be made to the server side JAX WS code Information about running the example application is included in lt JWSDP_HOME gt xws security samples jaxws2 simple doclit README txt and in the Java WSDP Tutorial For more information on XWSS e Read the Java Web Services Developer Pack Tutorial The tutorial can be accessed from http java sun com webservices docs htm1 e Read the XWSS samples documentation which is located in the
215. n import javax xml bind Marshaller import javax xml bind UnmarshalException import javax xml bind Unmarshal ler import javax xml bind ValidationEvent import javax xml bind util ValidationEventCol lector import primer po 2 A JAXBContext instance is created for handling classes generated in primer po JAXBContext jc JAXBContext newInstance primer po 3 An Unmarshal ler instance is created Unmarshaller u jc createUnmarshallerQ 4 The default JAXB Unmarshaller ValidationEventHandler is enabled to send to validation warnings and errors to system out The default config uration causes the unmarshal operation to fail upon encountering the first validation error u setValidating true 5 An attempt is made to unmarshal po xm1 into a Java content tree For the purposes of this example the po xm1 contains a deliberate error PurchaseOrder po PurchaseOrder u unmarshal new FileInputStream po xm1 6 The default validation event handler processes a validation error generates output to system out and then an exception is thrown catch UnmarshalException ue System out printIn Caught UnmarshalException catch JAXBException je je printStackTraceQ catch IOException ioe joe printStackTraceQ Sample Output Running java Main for this example produces the following output DefaultValidationEventHandler ERROR 1 does not satisfy the positiveInteger type Caught Un
216. n Java System Application Server e Sun Java System Web Server e Apache Tomcat servlet container Samples for using XWS Security are included with Java WSDP in the directory lt JWSDP_HOME gt xws security samples or can be viewed online at http java sun com webservices docs 2 0 xws security samples html Configuring Message Securty Using XWSS The Application Server contains all of the JAR files necessary to use XWS Secu rity for securing JAX WS applications however in order to view the sample applications you must download and install the standalone Java WSDP bundle You can download the Java WSDP from http java sun com webservices downloads webservicespack htm To add message security to an existing JAX WS application using XWSS fol low these steps on the client side 1 Create a client security configuration The client security configuration file specifies the order and type of message security operations that will be used for the client application For example a simple security configura tion to perform a digital signature operation looks like this lt xml version 1 0 encoding UTF 8 gt lt xwss JAXRPCSecurity xmIns xwss http java sun com xml ns xwss config gt lt xwss Service conformance bsp gt lt xwss SecurityConfiguration dumpMessages true gt lt xwss Sign id s includeTimestamp true gt USING THE JAVA WSDP XWSS SECURITY IMPLEMENTATION 249 lt xwss X5 9Token encodingType http doc
217. n isSetBool Object getContent boolean isSetContent void unSetContentQ 66 USING JAXB Calling getContent returns the current value of the Choice content The setters of this choice are just like radio buttons setting one unsets the previously set one This class represents the data representing the choice Additionally the generated Java interface FooBarType representing the anony mous type definition for element FooBar contains a nested interface for the choice model group containing phoneNumber and speedDial Java toSchema Examples The Java to Schema examples show how to use annotations to map Java classes to XML schema j2s create marshal Example The j2s create marhal example illustrates Java to schema databinding It demon strates marshalling and unmarshalling of JAXB annotated classes The example also shows how to enable JAXP 1 3 validation at unmarshal time using a schema file that was generated from the JAXB mapped classes The schema file bc xsd was generated with the following commands schemagen src cardfile java cp schemal xsd bc xsd Note that schemal xsd was copied to bc xsd schemagen does not allow you to specify a schema name of your choice j2s xmlAccessorOrder Example The j2s xmlAccessorOrder example shows how to use the XmlAccessorOrder and XmlType propOrder annotations to dictate the order in which XML con tent is marshalled unmarshalled by a Java type Java to Schema
218. n password txt RUNNING THE SAMPLES 101 3 You may also need to specify the path to the asant command in your PATH environment variable for example on UNIX Linux export PATH PATH opt SUNWappserver bin or on Windows set PATH PATH c Sun AppServer bin asant is a script wrapper around the implementation of Ant bundled with the J2EE 1 4 Tutorial Be sure to use this Ant implementation when run ning the tutorial samples rather than any other Ant implementation you may have installed on your system Also be sure to use the asant wrapper rather than running Ant directly 4 Finally note that the build xm1 files in the various stax sample directo ries include classpath references to lt javaee home gt lib javaee jar and lt javaee home gt 1ib appserv ws jar You should not change these val ues and if you create your own build xml files be sure to include these classpath references Running the Samples The samples are run by means of the asant Ant wrapper and three build targets defined in the lt javaee tutorial home gt stax samples bui1ld xm1 file When you run any of the samples the compiled class files are placed in a directory named build This directory is created if it does not exist already Note As mentioned above be sure to use the implementation of Ant bundled with the J2EE Tutorial rather than any version of Ant you may already have installed on your system Also be sure to use the asant wrapper script
219. n the command line to search the registry for specification concepts whose names contain that string For example the following command line searches for concepts whose names contain the string helloconcept searching is not case sensitive asant Dquery string helloconcept run query wsd1 This example finds the concept and organization you published Deleting a Concept To run the JAXRDeleteConcept program specify the UUID string displayed by the JAXRPublishConcept program as input to the run delete concept target asant Duuid string uuidString run delete concept Do not delete the concept until after you have deleted any organizations that refer to it Getting a List of Your Registry Objects To get a list of the objects you own in the registry organizations classification schemes and concepts run the JAXRGetMyObjects program by using the run get objects target asant run get objects 205 206 JAVA API FOR XML REGISTRIES Other Targets To remove the build directory and class files use the command asant clean To obtain a syntax reminder for the targets use the command asant projecthelp Using J AXR Clients in Java EE Applications You can create Java EE applications that use JAXR clients to access registries This section explains how to write compile package deploy and run a Java EE application that uses JAXR to publish an organization to a registry and then query the registry for that organization
220. n the form of a web based service Currently there are a variety of specifications for XML registries These include e The ebXML Registry and Repository standard which is sponsored by the Organization for the Advancement of Structured Information Standards OASIS and the United Nations Centre for the Facilitation of Procedures and Practices in Administration Commerce and Transport U N CEFACT e The Universal Description Discovery and Integration UDDI project which is being developed by a vendor consortium A registry provider is an implementation of a business registry that conforms to a specification for XML registries What Is J AXR JAXR enables Java software programmers to use a single easy to use abstrac tion API to access a variety of XML registries A unified JAXR information model describes content and metadata within XML registries JAXR gives developers the ability to write registry client programs that are por table across various target registries JAXR also enables value added capabilities beyond those of the underlying registries The current version of the JAXR specification includes detailed bindings between the JAXR information model and both the ebXML Registry and the UDDI version 2 specifications You can find the latest version of the specifica tion at http java sun com xml downloads jaxr htm At this release of the Application Server the JAXR provider implements the level 0 capability profile
221. nDesk xmIns ns http gizmos com NSURI env mustUnderstand true env role http gizmos com confirmations gt lt ns billingDesk xmIns ns http gizmos com NSURI env relay true env role http gizmos com billing gt lt env Header gt lt env Body gt lt env Envelope gt Header name is http gizmos com NSURI orderDesk Role is http gizmos com orders mustUnderstand is false relay is false Header name is http gizmos com NSURI shippingDesk Role is http gizmos com shipping mustUnderstand is false relay is false Header name is http gizmos com NSURI confi rmationDesk Role is http gizmos com confirmations mustUnderstand is true relay is false Header name is http gizmos com NSURI bi11ingDesk Role is http gizmos com billing mustUnderstand is false relay is true DOMExample java and DOMSic Example java The examples DOMExample java and DOMSrcExample java show how to add a DOM document to a message and then traverse its contents They show two ways to do this e DOMExample java creates a DOM document and adds it to the body of a message e DOMSrcExample java creates the document uses it to create a DOMSource object and then sets the DOMSource object as the content of the message s SOAP part You will find the code for DOMExample and DOMSrcExample in the following directory lt INSTALL gt javaeetutorial5 examples saaj dom src DOMEXAMPLE JAVA AND DOMSRCEXAMPLE JAVA 163 Exam
222. nce method for SOAPConnectionFactory the newInstance method for MessageFactory is static so you invoke it by calling MessageFactory newInstance If you specify no arguments to the newInstance method it creates a message factory for SOAP 1 1 messages To create a message factory that allows you to create and process SOAP 1 2 messages use the following method call MessageFactory factory MessageFactory newInstance SOAPConstants SOAP_1_2_PROTOCOL To create a message factory that can create either SOAP 1 1 or SOAP 1 2 mes sages use the following method call MessageFactory factory MessageFactory newInstance SOAPConstants DYNAMIC_SOAP_PROTOCOL This kind of factory enables you to process an incoming message that might be of either type Parts of a Message A SOAPMessage object is required to have certain elements and as stated previ ously the SAAJ API simplifies things for you by returning a new SOAPMessage object that already contains these elements When you call createMessage with no arguments the message that is created automatically has the following I A SOAPPart object that contains A A SOAPEnvelope object that contains 1 An empty SOAPHeader object 2 An empty SOAPBody object The SOAPHeader object is optional and can be deleted if it is not needed How ever if there is one it must precede the SOAPBody object The SOAPBody object can hold either the content of the message or a fault message that contai
223. nding The most basic interfaces in the javax xm1 registry package are e Connection The Connection interface represents a client session with a registry provider The client must create a connection with the JAXR pro vider in order to use a registry e RegistryService The client obtains a RegistryService object from its connection The RegistryService object in turn enables the client to obtain the interfaces it uses to access the registry The primary interfaces also part of the javax xml registry package are e BusinessQueryManager which allows the client to search a registry for information in accordance with the javax xml registry infomodel interfaces An optional interface DeclarativeQueryManager allows the client to use SQL syntax for queries The implementation of JAXR in the Application Server does not implement DeclarativeQueryManager e BusinessLifeCycleManager which allows the client to modify the infor mation in a registry by either saving it updating it or deleting it 173 174 JAVA API FOR XML REGISTRIES When an error occurs JAXR API methods throw a JAXRException or one of its subclasses Many methods in the JAXR API use a Collection object as an argument or a returned value Using a Collection object allows operations on several registry objects at a time Figure 6 1 illustrates the architecture of JAXR In the Application Server a JAXR client uses the capability level 0 interfaces of the JAXR API
224. ne of the methods it must be set on either the setter or getter method but not on both The j2s xmlAttribute field example shows how to use the XmlAttribute anno tationd on a static final field on a field rather than on one of the corresponding bean methods on a bean property method and on a field that is other than a collection type In class USAddress fields country and zip are tagged as attributes The setZip method was disabled to avoid the compile error Prop erty state was tagged as an attribute on the setter method You could have used the getter method instead In class PurchaseOrderType field cCardVendor is a J2S8 XMLROOTELEMENT EXAMPLE non collection type It meets the requirment of being a simple type it is an enum type j2s xmlRootHlement Example The j2s xmlRootElement example demonstrates the use of the XmlRootEle ment annotation to define an XML element name for the XML schema type of the corresponding class The XmlRootElement annotation maps a class or an enum type to an XML element At least one element definition is needed for each top level Java type used for unmarshalling marshalling If there is no element definition there is no starting location for XML content processing The XmlRootElement annotation uses the class name as the default element name You can change the default name by using the annotation attribute name If you do the specified name will then be used as the element name and the ty
225. ng of this type to java math BigInteger For the purposes of the Customize Inline example the restrictions on ZipCodeType specifically that legal US ZIP codes are limited to five digits make it so all valid values can eas ily fit within the Java primitive datatype int Note also that because lt jxb jav aType name int gt is declared within ZipCodeType the customization applies to all JAXB properties that reference this simpleType definition includ ing the getZip and setZip methods Datatype Converter Example The Datatype Converter example is very similar to the Customize Inline exam ple As with the Customize Inline example the customizations in the Datatype Converter example are made by using inline binding declarations in the XML schema for the application po xsd The global schema and package and most of the class customizations for the Customize Inline and Datatype Converter examples are identical Where the Datatype Converter example differs from the Customize Inline example is in the parseMethod and printMethod used for converting XML data to the Java int datatype Specifically rather than using methods in the custom MyDataTypeConverter class to perform these datatype conversions the Datatype Converter example uses the built in methods provided by javax xm bind DatatypeConverter lt xsd simpleType name ZipCodeType gt lt xsd annotation gt lt xsd appinfo gt lt jxb javaType name int parseMethod javax xml
226. ngC Server not responding The SOAP 1 2 code would look like this QName faultName new QName SOAPConstants URI_NS_SOAP_1_2_ENVELOPE Receiver fault setFaultCode faultName fault setFaultRoleC http gizmos com order fault addFaultReasonTextC Server not responding Locale US To add one or more subcodes to the fault code call the method fault append FaultSubcode which takes a QName argument The SOAPFault object fault created in the preceding lines of code indicates that the cause of the problem is an unavailable server and that the actor at http gizmos com orders is having the problem If the message were being routed only to its ultimate destination there would have been no need to set a fault actor Also note that fault does not have a Detail object because it does not relate to the SOAPBody object If you use SOAP 1 2 you can use the setFault Role method instead of setFau1tActor The following SOAP 1 1 code fragment creates a SOAPFau1t object that includes a Detail object Note that a SOAPFau1t object can have only one Detail object which is simply a container for DetailEntry objects but the Detail object can have multiple DetailEntry objects The Detail object in the following lines of code has two DetailEntry objects added to it SOAPFault fault body addFaultQ QName faultName new QName SOAPConstants URI_NS_SOAP_ENVELOPE Client fault setFaultCode faultName fault setFaultStringC Message do
227. ngs node xs element name Class gt lt jxb class name Clazz gt lt jxb property name Clazz gt lt jxb bindings gt The second conflict in example xsd the namespace collision between the ele ment FooBar and the complexType FooBar is resolved in binding xjb by using a lt nameXmlTransform gt declaration at the lt schemaBindings gt level to append the suffix Element to all element definitions This customization handles the case where there are many name conflicts due to systemic collisions between two symbol spaces usually named type definitions and global element declarations By appending a suffix or prefix to every Java identifier representing a specific XML symbol space this single customization resolves all name collisions lt jxb schemaBindings gt lt jxb package name example gt lt jxb nameXm1Transform gt lt jxb elementName suffix Element gt lt jxb nameXm1Transform gt lt jxb schemaBindings gt The third conflict in example xsd the namespace collision between the ele ment zip and the attribute zip is resolved in binding xjb by mapping the attribute zip to property named zipAttribute lt jxb bindings node xs attribute name zip gt lt jxb property name zipAttribute gt lt jxb bindings gt If you add the binding parameter you removed back to the xjc task in the build xm1 file and then run ant in the lt INSTALL gt examples jaxb fix col lides directory the customizations in
228. nism for request response messaging To send a message a SAAJ client can use a SOAPConnection object A SOAP Connection object is a point to point connection meaning that it goes directly from the sender to the destination usually a URL that the sender specifies The first step is to obtain a SOAPConnectionFactory object that you can use to create your connection The SAAJ API makes this easy by providing the SOAP ConnectionFactory class with a default implementation You can get an instance of this implementation using the following line of code SOAPConnectionFactory soapConnectionFactory SOAPConnectionFactory newInstance Now you can use soapConnectionFactory to create a SOAPConnection object SOAPConnection connection soapConnectionFactory createConnection 132 SOAP WITH ATTACHMENTS API FOR JAVA You will use connection to send the message that you created Sending a Message A SAAJ client calls the SOAPConnection method call on a SOAPConnection object to send a message The call method takes two arguments the message being sent and the destination to which the message should go This message is going to the stock quote service indicated by the URL object endpoint java net URL endpoint new URL http wombat ztrade com quotes SOAPMessage response connection call message endpoint The content of the message you sent is the stock symbol SUNW the SOAPMes sage object response should contain the la
229. nnotation precedes the XmlType propOrder annotation xmlAccessorOrder AccessorOrder ALPHABETICAL Xm1lType propOrder name city public class USAddress public String getCity return city public void setCity String city this city city public String getName return name public void setName String name this name name In the code below the XmlType propOrder annotation precedes the XmlAc cessorOrder annotation Xm1lType propOrder name city xmlAccessorOrder AccessorOrder ALPHABETICAL public class USAddress public String getCity return city public void setCity String city this city city public String getName return name public void setName String name this name name In both scenarios propOrder takes precedence and the identical schema content shown below will be generated lt xs complexType name usAddress gt lt xsS sequence gt lt xs element name name type xs string minOccurs 0 gt lt xs element name city type xs string minOccurs 0 gt lt xs Sequence gt lt xs complexType gt The purchase order code example demonstrates the affects of schema content ordering using the XmlAccessorOrder annotation at the package and class level and the XmlType propOrder annotation on a class Class package info java defines XmlAccessorOrder to be ALPHABETI CAL for the package The public fields shipTo and bil1To in class Pu
230. nnotations the lt typesafeEnumClass gt declaration must be specified in the annotation element of the lt simpleType gt element The lt typesafeEnum Member gt must be specified in the annotation element of the enumeration mem ber This allows the enumeration member to be customized independently from the enumeration class For information about typesafe enum design patterns see the sample chapter of Joshua Bloch s Effective Java Programming on the Java Developer Connection lt javadoc gt Binding Declarations The lt javadoc gt declaration lets you add custom Javadoc tool annotations to schema derived JAXB packages classes interfaces methods and fields Note that lt javadoc gt declarations cannot be applied globally that is they are only valid as a sub elements of other binding customizations The syntax for the lt javadoc gt customization is lt javadoc gt Contents in amp lt b gt Javadoc amp lt b gt format lt javadoc gt or lt javadoc gt lt lt CDATA Contents in lt b gt Javadoc lt b gt format gt lt javadoc gt Note that documentation strings in lt javadoc gt declarations applied at the pack age level must contain lt body gt open and close tags for example lt jxb package name primer myPo gt lt jxb javadoc gt lt CDATA lt body gt Package level documentation for generated package primer myPo lt body gt gt lt jxb javadoc gt lt jxb package gt Customi
231. not hurt to call it explicitly message saveChanges The following lines display the message that will be sent System out printInC n Request Message n message writeTo System out The next line of code creates the java net URL object that represents the desti nation for this message It gets the value of the property named URL from the sys tem properties URL endpoint new URLC System getProperties getPropertyC URL MYUDDIPING JAVA 157 Next the message message is sent to the destination that endpoint represents which is the UDDI test registry The cal1 method will block until it gets a SOAP Message object back at which point it returns the reply SOAPMessage reply connection call message endpoint In the next lines of code the first line prints a line giving the URL of the sender the test registry and the others display the returned message System out printInC n nReceived reply from endpoint System out println n Reply Message n reply writeTo System out The returned message is the complete SOAP message an XML document as it looks when it comes over the wire It is a businessList that follows the format specified in http uddi org pubs DataStructure V2 03 Published 20020719 htm _Toc25130802 As interesting as it is to see the XML that is actually transmitted the XML docu ment format does not make it easy to see the text that is the message s content To r
232. notation For example if XmlAccessorOrder Accesso rOrder ALPHABETICAL is defined on a package and XmlAccesso rOrder AccessorOrder UNDEFINED is defined on a class in that package the contents of the generated schema type for the class would be in an unspecified order and the contents of the generated schema type for evey other class in the package would be alphabetical order The XmlType annotation can be defined for a class The annotation element propOrder in the XmlType annotation allows you to specify the content order in the generated schema type When you use the XmlType propOrder annotation on a class to specify content order all public properties and public fields in the class must be specified in the parameter list Any public property or field that you want to keep out of the parameter list must be annotated with XmlAttribute or XmITransient we The default content order for XmlType propOrder is or not active In such cases the active xXmlAccessorOrder annotation takes precedence When class content order is specified by the XmlType propOrder annotation it takes precedence over any active XmlAccessorOrder annotation on the class or package If the XmlAccessorOrder and XmlType propOrder A B annotations are specified on a class the propOrder always takes precedence regardless of the order of the annontation statements For example in the code 67 68 USING JAXB below the XmlAccessorOrder a
233. ns status 125 126 SOAP WITH ATTACHMENTS API FOR JAVA information or details about a problem with the message The section Using SOAP Faults page 145 walks you through how to use SOAPFau1t objects Accessing Elements of a Message The next step in creating a message is to access its parts so that content can be added There are two ways to do this The SOAPMessage object message created in the preceding code fragment is the place to start The first way to access the parts of the message is to work your way through the structure of the message The message contains a SOAPPart object so you use the getSOAPPart method of message to retrieve it SOAPPart soapPart message getSOAPPartQ Next you can use the getEnvelope method of soapPart to retrieve the SOAPEn ve lope object that it contains SOAPEnvelope envelope soapPart getEnvelope You can now use the getHeader and getBody methods of envelope to retrieve its empty SOAPHeader and SOAPBody objects SOAPHeader header envelope getHeader SOAPBody body envelope getBodyQ The second way to access the parts of the message is to retrieve the message header and body directly without retrieving the SOAPPart or SOAPEnve lope To do so use the getSOAPHeader and getSOAPBody methods of SOAPMessage SOAPHeader header message getSOAPHeader SOAPBody body message getSOAPBody This example of a SAAJ client does not use a SOAP header so you can delete
234. nt To publish the location of the WSDL document for the JAX WS He11o service first deploy the service to the Application Server as described in Creating a Sim ple Web Service and Client with JAX WS page xvi Then run the JAXRPublishConcept program using the run publish concept target asant run publish concept The program output displays the UUID string of the new specification concept which is named HelloConcept You will use this string in the next section After you run the JAXRPublishConcept program you can run JAXRPublish Hel1lo0rg to publish an organization that uses this concept Publishing an Organization with a WSDL Document in Its Service Binding To run the JAXRPublishHel1loOrg example use the asant target run publish hello org Specify the string returned from JAXRPublishConcept including the uuid prefix as input to this target asant Duuid string uuidstring run publish hello org RUNNING THE EXAMPLES The uuidstring would look something like this uuid 10945f5c f2e1 0945 2f07 5897ebcfaa35 The program output displays the string value of the key of the new organization which is named Hello Organization After you publish the organization run the JAXRQueryByWSDLClassification example to search for it To delete it run JAXRDelete Running the J AXRQueryByWSDLC lassifx ation Example To run the JAXRQueryByWSDLClassification example use the asant target run query wsd1 Specify a query string argument o
235. nt Examples page 199 and a Java EE application example described in Using JAXR Clients in Java EE Applications page 206 The examples are in the directory lt INSTALL gt javaeetutorial5 examples jaxr lt INSTALL gt is the directory where you installed the tutorial bundle Each example directory has a build xml file which refers to a targets xm1 file and a build proper ties file in the directory lt INSTALL gt javaeetutorial5 examples jaxr com mon Establishing a Connection The first task a JAXR client must complete is to establish a connection to a regis try Establishing a connection involves the following tasks e Preliminaries Getting access to a registry e Creating or looking up a connection factory e Creating a connection e Setting connection properties e Obtaining and using a RegistryService object Preliminaries Getting Access to a Registry To use the Java WSDP Registry Server a private UDDI version 2 registry you need to download and install Java WSDP 1 5 and then to install the Registry Server in the Application Server To download Java WSDP 1 5 perform these steps 1 Go to the following URL http java sun com webservices downloads 1 5 index htm 2 Under Java Web Services Developer Pack v1 5 click Download 175 176 JAVA API FOR XML REGISTRIES 3 On the Login page click the Download link You do not have to log in 4 Select the Accept radio button to accept the license agreement
236. ntact for organization org setPrimaryContact primaryContact Adding Classifications Organizations commonly belong to one or more classifications based on one or more classification schemes taxonomies To establish a classification for an organization using a taxonomy the client first locates the taxonomy it wants to use It uses the BusinessQueryManager to find the taxonomy The findClassificationSchemeByName method takes a set of FindQualifier objects as its first argument but this argument can be null Set classification scheme to NAICS ClassificationScheme cScheme bqm findClassificationSchemeByName nul1 ntis gov naics 1997 The client then creates a classification using the classification scheme and a con cept a taxonomy element within the classification scheme For example the following code sets up a classification for the organization within the NAICS taxonomy The second and third arguments of the createClassification method are the name and the value of the concept Create and add classification InternationalString sn blcm createInternationalString All Other Specialty Food Stores String sv 445299 Classification classification blcm createClassification cScheme sn sv Collection lt Classification gt classifications new ArrayList lt Classification gt Q classifications add classification org addClassifications classifications Services also use classifications so you can use s
237. o specify the Signature element that we want to validate since there could be more than one in the document We use the DOM method Docu VALIDATE EXAMPLE ment getElementsByTagNameNS passing it the XML Signature namespace URI and the tag name of the Signature element as shown NodeList nl doc getElementsByTagNameNS XMLSignature XMLNS Signature if nl getLength Q throw new Exception Cannot find Signature element This returns a list of all Signature elements in the document In this example there is only one Signature element Creating a Validation Context We create an XMLValidateContext instance containing input parameters for val idating the signature Since we are using DOM we instantiate a DOMValidate Context instance a subclass of XMLValidateContext and pass it two parameters a KeyValueKeySelector object and a reference to the Signature element to be validated which is the first entry of the NodeList we generated earlier DOMValidateContext valContext new DOMValidateContext new KeyValueKeySelector nl item Q The KeyValueKeySelector is explained in greater detail in Using KeySelectors page 225 Unmarshaling the XML Signature We extract the contents of the Signature element into an XMLSignature object This process is called unmarshalling The Signature element is unmarshalled using an XMLSignatureFactory object An application can obtain a DOM implementation of XMLSignatureFacto
238. on to specify an alternate output directory The directory must already exist xjc will not create it for you p package Specify an alternate output directory By default the XJC binding compiler will generate the Java content classes in the current direc tory The output directory must already exist the XJC binding com piler will not create it for you proxy proxy Specify the HTTP HTTPS proxy The format is user pass word proxyHost proxyPort The old host and port options are still supported by the Reference Implementation for backwards compatibility but they have been deprecated classpath arg Specify where to find client application class files used by the lt jxb javaType gt and lt xjc superClass gt customizations catalog file Specify catalog files to resolve external entity references Supports TR9401 XCatalog and OASIS XML Catalog format For more information please read the XML Entity and URI Resolvers docu ment or examine the catalog resolver sample application readOnly Force the XJC binding compiler to mark the generated Java sources read only By default the XJC binding compiler does not write pro tect the Java source files it generates Supress the generation of package level annotations into pack age info java Using this switch causes the generated code to internalize those annotations into the other generated classes xml schema Treat input schemas a
239. onse bqm findOrganizations null null classifications null null null Collection orgs response getCollection You can also use classifications to find organizations that offer services based on technical specifications that take the form of WSDL Web Services Description Language documents In JAXR a concept is used as a proxy to hold the infor mation about a specification The steps are a little more complicated than in the preceding example because the client must first find the specification concepts and then find the organizations that use those concepts The following code fragment finds all the WSDL specification instances used within a given registry You can see that the code is similar to the NAICS query 183 184 JAVA API FOR XML REGISTRIES code except that it ends with a call to findConcepts instead of findOrganiza tions String schemeName uddi org types ClassificationScheme uddiOrgTypes bqm findClassificationSchemeByName null schemeName Create a classification specifying the scheme and the taxonomy name and value defined for WSDL documents by the UDDI specification 3 Classification wsdlSpecClassification blcm createClassification uddiOrgTypes wsdlSpec wsd1Spec Collection lt Classification gt classifications new ArrayList lt Classification gt Q classifications add wsd1SpecClassi fication Find concepts BulkResponse br bqm findConcepts null null
240. or The default value is false enableFai1FastCheck can be either true false 1 or 0 If enableFai1 FastCheck is true or 1 and the JAXB implementation supports this optional checking type constraint checking is performed when setting a property The default value is false Please note that the JAXB implemen tation does not support failfast validation choiceContentProperty can be either true false 1 or 0 The default value is false choiceContentProperty is not relevant when the bind ingStyle is elementBinding Therefore if bindingSty1e is specified as elementBinding then the choiceContentProperty must result in an invalid customization underscoreBinding can be either asWwordSeparator or asCharInwWord The default value is asWordSeparator enableJavaNamingConventions can be either true false 1 or 0 The default value is true typesafeEnumBase can be a list of QNames each of which must resolve to a simple type definition The default value is xs NCName See Typesafe CUSTOMIZATION OVERVIEW 43 Enumeration Binding Declarations page 47 for information about local ized mapping of simpleType definitions to Java typesafe enum classes e typesafeEnumMemberName can be either generateError or generate Name The default value is generateError e bindingStyle can be either elementBinding or modelGroupBinding The default value is elementBinding e lt javaType gt can be zero or more javaType binding declarations See lt
241. or Sample CursorParse java page 103 cursor2event Sample CursorApproachEventObject java page 105 event Sample EventParse java page 106 filter Sample MyStreamFilter java page 109 readnwrite Sample EventProducerConsumer java page 111 writer Sample CursorWriter java page 114 Sample Code Organization There are seven StAX sample directories in lt javaee tutorial home gt exam ples stax common contains a build properties file and a target xm file that are used commonly by all the StAX tutorial examples There is also a data directory containing a sample XML document BookCatalog xml that is used by all the StAX examples The values in common bui1d properties as well as all the StAX examples are inherited from a parent build prop erties file in the lt javaee tutorial home gt examples common direc tory Note that you should not need to modify the build properties file in stax common bui ld properties cursor contains CursorParse java which illustrates how to use the XML StreamReader cursor API to read an XML file cursor2event contains CursorApproachEventObject java which illus trates how an application can get information as an XMLEvent object when using cursor API 99 100 STREAMING API FOR XML e event contains EventParse java which illustrates how to use the XMLEv entReader event iterator API to read an XML file e filter contains MyStreamFilter java which illustrates how
242. or the SOAP header all the parts listed are required to be in every SOAP message I SOAP message A SOAP part 1 SOAP envelope a SOAP header optional b SOAP body The SAAJ API provides the SOAPMessage class to represent a SOAP message the SOAPPart class to represent the SOAP part the SOAPEnvelope interface to represent the SOAP envelope and so on Figure 5 1 illustrates the structure of a SOAP message with no attachments Note Many SAAJ API interfaces extend DOM interfaces In a SAAJ message the SOAPPart class is also a DOM document See SAAJ and DOM page 122 for details When you create a new SOAPMessage object it will automatically have the parts that are required to be in a SOAP message In other words a new SOAPMessage object has a SOAPPart object that contains a SOAPEnvelope object The SOAPEn velope object in turn automatically contains an empty SOAPHeader object fol lowed by an empty SOAPBody object If you do not need the SOAPHeader object which is optional you can delete it The rationale for having it automatically included is that more often than not you will need it so it is more convenient to have it provided 119 120 SOAP WITH ATTACHMENTS API FOR JAVA The SOAPHeader object can include one or more headers that contain metadata about the message for example information about the sending and receiving parties The SOAPBody object which always follows the SOAPHeader object if there is one contain
243. ou must set javaee home as fol lows javaee home C Sun AppServer or javaee home C Sun AppServer e Set the javaee tutorial home property to the location of your tutorial This property is used for asant deployment and undeployment For example on UNIX javaee tutorial home home username javaeetutorial5 On Windows javaee tutorial home C javaeetutorial5 ABOUT THIS TUTORIAL xiii Do not install the tutorial to a location with spaces in the path e If you did not use the default value admin for the admin user set the admin user property to the value you specified when you installed the Application Server e If you did not use port 8080 set the domain resources port property to the value specified when you installed the Application Server e Set the admin user s password in lt INSTALL gt javaeetutorial5 examples common admin pass word txt to the value you specified when you installed the Application Server The format of this file is AS_ADMIN_PASSWORD password For example AS_ADMIN_PASSWORD mypas sword How to Print This Tutonal To print this tutorial follow these steps 1 Ensure that Adobe Acrobat Reader is installed on your system 2 Open the PDF version of this book 3 Click the printer icon in Adobe Acrobat Reader Typographical Conventions Table 2 lists the typographical conventions used in this tutorial Table 2 Typographical Conventions Font Style italic Emphasis titles
244. ource This attribute specifies the type of required authentica tion either sender user name and password or content digital sig nature This is an attribute of the request protection and response protection elements e auth recipient This attribute specifies whether recipient authentica tion occurs before or after content authentication Allowed values are before content and after content This is an attribute of the request protection and response protection elements For more detailed information on configuring application specific web services security refer to the Application Server s Developer s Guide For more detailed information on the elements used for message security binding read the Appli cation Server s Application Deployment Guide For a link to these documents see Further Information page 251 Example Using Application Server WS Security The Application Server ships with sample applications named xms and xms_apl_lv1 Both applications features a simple web service that is imple mented by both a Java EE EJB endpoint and a Java Servlet endpoint Both end points share the same service endpoint interface The service endpoint interface defines a single operation sayHello which takes a String argument and returns a String composed by pre pending He11o to the invocation argument e The xms application shows how to enable message layer security at the Application Server level by enabling the Application Ser
245. pe name It is common schema practice for the element and type names to be differ ent You can use the XmlType annotation to set the element type name The namespace attribute of the XmlRootElement annotation is used to define a namespace for the element j2s xmlSc hemaType class Example The j2s XmlSchemaType class example demonstrates the use of the annotation XmlSchemaType to customize the mapping of a property or field to an XML built in type The XmlSchemaType annotation can be used to map a Java type to one of the XML built in types This annotation is most useful in mapping a Java type to one of the nine date time primitive datatypes When the XmlSchemaType annotation is defined at the package level the identification requires both the XML built in type name and the corresponding Java type class A XmlSchemaType definition on a field or property takes pre cedence over a package definition The j2s XmlSchemaType clasexample shows how to use the XmlSchemaType annotation at the package level on a field and on a property File TrackingOrder has two fields orderDate and deliveryDate which are defined to be of type XMLGregorianCalendar The generated schema will define these elements to be 73 74 USING JAXB of XML built in type gMonthDay This relationship was defined on the package in the file package info java Field shipDate in file TrackingOrder is also defined to be of type XMLGregorianCalendar but the XmlSchema
246. pe gt customization package primer import java math BigInteger import javax xml bind DatatypeConverter public class MyDatatypeConverter public static short parseIntegerToShort String value BigInteger result DatatypeConverter parseInteger value return short Cresult intValueQ public static String printShortToInteger short value BigInteger result BigInteger valueOf value return DatatypeConverter printInteger result public static int parseIntegerToInt String value BigInteger result DatatypeConverter parseInteger value return result intValueQ public static String printIntToInteger int value BigInteger result BigInteger valueOf value return DatatypeConverter printInteger result The following code shows how the MyDatatypeConverter class is referenced in a lt javaType gt declaration in po xsd lt xsd simpleType name ZipCodeType gt lt xsd annotation gt lt xsd appinfo gt lt jxb javaType name int parseMethod primer MyDatatypeConverter parseIntegerToInt printMethod primer MyDatatypeConverter printIntTo Integer gt lt xsd appinfo gt lt xsd annotation gt DATATYPE CONVERTER EXAMPLE lt xsd restriction base xsd integer gt lt xsd mininclusive value 10000 gt lt xsd maxInclusive value 99999 gt lt xsd restriction gt lt xsd simpleType gt In this example the jxb javaType binding declaration overrides the default JAXB bindi
247. ple times 1 Run the JAXRPublishPostal program Specify the string you entered in the postalconcepts xm1 file including the uuid prefix as input to the run publish postal target asant Duuid string uuidstring run publish postal The uuidstring would look something like this uuid 938d9ccd a74a 4c7e 864a e6e2c6822519 The program output displays the string value of the key of the new organi zation 2 Run the JAXRQueryPostal program The run query postal target spec ifies the postalconcepts xm1 file in a lt sysproperty gt tag As input to the run query postal target specify both a query string argument and a uuid string argument on the command line to search the registry for the organization published by the run publish postal target asant Dquery string coffee Duuid string uuidstring run query postal 204 JAVA API FOR XML REGISTRIES The postal address for the primary contact will appear correctly with the JAXR PostalAddress methods Any postal addresses found that use other postal address schemes will appear as Slot lines If you want to delete the organization you published follow the instructions in Running the JAXRDelete Example page 202 Deleting a Classification Scheme To delete the classification scheme you published after you have finished using it run the JAXRDeleteScheme program using the run delete scheme target asant Duuid string uuidstring run delete scheme Publishing a Concept fora WSDL Docume
248. r 111 112 STREAMING API FOR XML The StAX XMLEventWriter API extends from the XMLEventConsumer interface and is referred to as an event consumer By contrast XMLEventReader is an event producer StAX supports simultaneous reading and writing such that it is possi ble to read from one XML stream sequentially and simultaneously write to another stream This sample shows how the StAX producer consumer mechanism can be used to read and write simultaneously This sample also shows how a stream can be modified and new events can be added dynamically and then written to different stream Creating an Event Produc er Consumer The first step is to instantiate an event factory and then create an instance of an event producer consumer XMLEventFactory m_eventFactory XMLEventFactory newlInstance public EventProducerConsumer try EventProducerConsumer ms new EventProducerConsumer XMLEventReader reader XMLInputFactory newInstance createXMLEventReader new java io FileInputStream args Q XMLEventWriter writer XMLOutputFactory newInstance createXMLEventwWriter System out J3 Creating an iterator The next step is to create an iterator to parse the stream whi leCreader hasNext XMLEvent event XMLEvent reader next ifCevent getEventTypeQ event CHARACTERS writer add ms getNewCharactersEvent event asCharacters READNWRITE SAMPLE EVENTPRODUCERCONSUMER JAVA 113 el
249. r the wsgen tool and the Application Server provide the Application Server s implementation of JAX WS These are the basic steps for creating the web service and client 1 Code the implementation class 2 Compile the implementation class 3 Use wsgen to generate the artifacts required to deploy the service 4 Package the files into a WAR file xviii BUILDING WEB SERVICES WITH JAX WS 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 7 8 Compile the client class 9 Use wsimport to generate and compile the stub files Run the client The sections that follow cover these steps in greater detail Requirements of a J AX WS Endpoint JAX WS endpoints must follow these requirements The implementing class must be annotated with either the javax jws WebService or javax jws WebServiceProvider annota tion The implementing class may explicitly reference an SEI through the end pointInterface element of the WebService annotation but is not required to do so If no endpointInterface is not specified in WebService an SEI is implicityly defined for the implementing class The business methods of the implementing class must be public and must not be declared static or final Business methods that are exposed to web service clients must be anno tated with javax jws WebMethod Business methods t
250. r you can use the default user name and password testuser and testuser ESTABLISHING A CONNECTION 177 Obtaining a Connection Factory A client creates a connection from a connection factory A JAXR provider can supply one or more preconfigured connection factories Clients can obtain these factories by using resource injection At this release of the Application Server JAXR supplies a connection factory through the JAXR RA but you need to use a connector resource whose JNDI name is eis JAXR to access this connection factory from a Java EE application To inject this resource in a Java EE component use code like the following import javax annotation Resource import javax xml registry ConnectionFactory Resource mappedName eis JAXR public ConnectionFactory factory Later in this chapter you will learn how to create this connector resource To use JAXR in a stand alone client program you must create an instance of the abstract class ConnectionFactory import javax xml registry ConnectionFactory ConnectionFactory connFactory ConnectionFactory newInstance Creating a Connection To create a connection a client first creates a set of properties that specify the URL or URLs of the registry or registries being accessed For example the fol lowing code provides the URLs of the query service and publishing service for a hypothetical registry There should be no line break in the strings Properties props new
251. r directly to its destination This kind of connection is called a point to point connection because it goes from one endpoint to another endpoint Messages sent using the SAAJ API are called request response messages They are sent over a SOAPConnection object with the call method which sends a message a request and then blocks until it receives the reply a response SOAPC onnection Objects The following code fragment creates the SOAPConnection object connection and then after creating and populating the message uses connection to send the message As stated previously all messages sent over a SOAPConnection object are sent with the call method which both sends the message and blocks TUTORIAL until it receives the response Thus the return value for the cal1 method is the SOAPMessage object that is the response to the message that was sent The request parameter is the message being sent endpoint represents where it is being sent SOAPConnectionFactory factory SOAPConnectionFactory newInstance SOAPConnection connection factory createConnection create a request message and give it content java net URL endpoint new URLC http fabulous com gizmo order SOAPMessage response connection call request endpoint Note that the second argument to the call method which identifies where the message is being sent can be a String object or a URL object Thus the last two lines of code from the preceding example
252. rather than running Ant directly There is a separate build xm1 file in each of the stax sample directories except common and each build xm1 file provides the same three targets Switch to the directory containing the sample you want to run and then run the desired build xm1 target from there 102 STREAMING API FOR XML The three Ant targets defined in each of the StAX build xml files are build Compile and run all classes e run Run the example e clean Clean all compiled files and sample directories when you are done For example to run the cursor example cd lt javaee tutorial home gt examples stax cursor asant build asant run Sample XML Document The sample XML document BookCatalogue xm1 used by most of the StAX sample classes is located in the lt javaee tutorial home gt exam ples stax common data directory and is a simple book catalog based on the common BookCatalogue namespace The contents of BookCatalogue xm1 are listed below lt xml version 1 0 encoding UTF 8 gt lt BookCatalogue xmIns http www publishing org gt lt Book gt lt Title gt Yogasana Vijnana the Science of Yoga lt Title gt lt author gt Dhirendra Brahmachari lt Author gt lt Date gt 1966 lt Date gt lt ISBN gt 81 40 34319 4 lt ISBN gt lt Publisher gt Dhirendra Yoga Publications lt Publisher gt lt Cost currency INR gt 11 50 lt Cost gt lt Book gt lt Book gt lt Title gt The First and Last Freedom
253. rchase J2S XMLADAPTER FIELD EXAMPLE OrderType will be affected in the generated schema content order by this rule Class USAddress defines the XmlType propOrder annotation on the class This demonstates user defined property order superseding ALPHABETICAL order in the generated schema The generated schema file can be found in directory schemas j2s xmlAda pter field Example The j2s xmlAdapter field example demonstrates how to use the XmlAdapter interface and the XmlJavaTypeAdapter annotation to provide a custom map ping of XML content into and out of a HashMap field that uses an int as the key and a string as the value Interface XmlAdapter and annotation XmlJavaTypeAdapter are used for spe cial processing of datatypes during unmarshalling marshalling There are a vari ety of XML datatypes for which the representation does not map easily into Java for example xs DateTime and xs Duration and Java types which do not map conveniently into XML representations for example implementations of java util Collection such as List and java util Map such as HashMap or for non JavaBean classes Itis for these cases that The XmlAdapter interface and the XmlJavaTypeAdapter annotation are pro vided for cases such as these This combination provides a portable mechanism for reading writing XML content into and out of Java applications 69 70 USING JAXB The XmlAdapter interface defines the methods for data reading writ
254. read ability Here is what the XML message looks like lt SOAP ENV Envelope xmIns SOAP ENV http schemas xmlsoap org soap envelope gt SOAPFAULTTEST JAVA 169 lt SOAP ENV Header gt lt SOAP ENV Body gt lt SOAP ENV Fault gt lt faultcode gt SOAP ENV Client lt faultcode gt lt faultstring gt Message does not have necessary info lt faultstring gt lt faultactor gt http gizmos com order lt faultactor gt lt detail gt lt PO order xmlns PO http gizmos com orders gt Quantity element does not have a value lt PO order gt lt PO confirmation xmIns PO http gizmos com confirm gt Incomplete address no zip code lt PO confirmation gt lt detai l gt lt SOAP ENV Fault gt lt SOAP ENV Body gt lt SOAP ENV Envelope gt SOAP fault contains Fault code http schemas xmlsoap org soap enve lope Client Local name Client Namespace prefix SOAP ENV bound to http schemas xmlsoap org soap envelope Fault string Message does not have necessary info Fault actor http gizmos com order Detail entry Quantity element does not have a value Detail entry Incomplete address no zip code When you run SOAPFaultTest to generate a SOAP 1 2 message the output looks like this Here is what the XML message looks like lt env Envelope xmlIns env http www w3 org 2003 05 soap enve lope gt lt env Header gt lt env Body gt lt env Fault gt lt env Code gt lt env Value gt env
255. reates a proxy a local object representing the service and then simply invokes methods on the proxy With JAX WS the developer does not generate or parse SOAP messages It is the JAX WS runtime system that converts the API calls and responses to and from SOAP messages With JAX WS clients and web services have a big advantage the platform inde pendence of the Java programming language In addition JAX WS is not restric tive a JAX WS client can access a web service that is not running on the Java XV xvi BUILDING WEB SERVICES WITH JAX WS platform and vice versa This flexibility is possible because JAX WS uses tech nologies defined by the World Wide Web Consortium W3C HTTP SOAP and the Web Service Description Language WSDL WSDL specifies an XML for mat for describing a service as a set of endpoints operating on messages Setting the Port Several files in the JAX WS examples depend on the port that you specified when you installed the Application Server The tutorial examples assume that the server runs on the default port 8080 If you have changed the port you must update the port number in the following files before building and running the JAX WS examples e lt INSTALL gt javaeetutorial5 examples jaxws simpleclient HelloClient java Creating a Smple Web Service and Client with J AX WS This section shows how to build and deploy a simple web service and client The source code for the service is in lt INSTA
256. rily pursues its mission through the creation of Web standards OASIS SPECIFICATIONS and guidelines The W3C is working on the following specifications related to web services security e XML Encryption XML Enc This specification provides requirements for XML syntax and processing for encrypting digital content including portions of XML documents and protocol messages The version of the specification current at the time of this writing may be viewed at http www w3 org TR 2002 REC xmlenc core 20021210 e XML Digital Signature XML Sig This specification specifies an XML compliant syntax used for represent ing the signature of web resources and portions of protocol messages anything referenceable by a URI and procedures for computing and ver ifying such signatures The version of the specification current at the time of this writing may be viewed at http www w3 org TR 2002 REC xmld sig core 20020212 e XML Key Management Specification XKMS The specification specifies protocols for distributing and registering pub lic keys suitable for use in conjunction with the W3C recommendations for XML Signature and XML Encryption The version of the specification current at the time of this writing may be viewed at http www w3 org TR 2005 REC xkms2 20050628 OASIS Specifications According to its web site at http www oasis open org the Organization for the Advancement of Structured Information Standards OASIS drives
257. rity with Java EE page 241 Advantages of Message Sec unty Before we get to message security it is important to understand why security at the transport layer is not always sufficient to address the security needs of a web service Transport layer security is provided by the transport mechanisms used to transmit information over the wire between clients and providers thus trans port layer security relies on secure HTTP transport HTTPS using Secure Sock ets Layer SSL Transport security is a point to point security mechanism that can be used for authentication message integrity and confidentiality When run ning over an SSL protected session the server and client can authenticate one another and negotiate an encryption algorithm and cryptographic keys before the application protocol transmits or receives its first byte of data Security is live from the time it leaves the consumer until it arrives at the provider or vice versa 234 SECURING WEB SERVICES even across intermediaries The problem is that it is not protected once it gets to its destination One solution is to encrypt the message before sending using mes sage security In message layer security security information is contained within the SOAP message and or SOAP message attachment which allows security information to travel along with the message or attachment For example a portion of the message may be signed by a sender and encrypted for a particular recei
258. rs IswhiteSpace false qname Cost EndElement namespaces null isCData false data n Characters IsWhiteSpace true qname Book EndElement namespaces null isCData false data n Characters IswWhiteSpace true qname BookCatalogue http www publishing org namespaces BookCatalogue gt http www publishing org EndElement EndDocument There are several important things to note in the above example e The events are created in the order in which the corresponding XML ele ments are encountered in the document including nesting of elements CHOOSING BETWEEN CURSOR AND ITERATOR APIS opening and closing of elements attribute order document start and doc ument end and so forth e As with proper XML syntax all container elements have corresponding start and end events for example every StartElement has a correspond ing EndElement even for empty elements e Attribute events are treated as secondary events and are accessed from their corresponding StartElement event e Similar to Attribute events Namespace events are treated as secondary but appear twice and are accessible twice in the event stream first from their corresponding StartElement and then from their corresponding EndElement e Character events are specified for all elements even if those elements have no character data Similarly Character events can be split across events e Th
259. rue if there are more events to process in the stream e peek Returns the event but does not iterate to the next event For example the following code snippet illustrates the XMLEventReader method declarations package javax xml stream import java util Iterator public interface XMLEventReader extends Iterator public Object next public XMLEvent nextEvent throws XMLStreamException public boolean hasNext public XMLEvent peek throws XMLStreamException To read all events on a stream and then print them you could use the following while stream hasNextQ XMLEvent event stream nextEventQ System out print Cevent Reading Atinbutes You can access attributes from their associated javax xml stream StartEle ment as follows public interface StartElement extends XMLEvent public Attribute getAttributeByName QName name public Iterator getAttributesQ You can use the getAttributes method on the StartElement interface to use an Iterator over all the attributes declared on that StartElement Reading Namespaces Similar to reading attributes namespaces are read using an Iterator created by calling the getNamespaces method on the StartElement interface Only the namespace for the current StartElement is returned and an application can get WRITING XML STREAMS the current namespace context by using StartElement getNamespaceCon text Writing XML Steams StAX is a bidirectional API and
260. rvices uddi name is truncated value is false name is xmlns value is urn uddi org api_v2 You can use either domsrc1 xm1 or domsrc2 xml1 to run DOMSrcExample To run DOMSrcExample use a command like the following asant run domsrc Dxm1 file domsrc2 xm1 166 SOAP WITH ATTACHMENTS API FOR JAVA When you run DOMSrcExample using the file domsrc2 xm1 you will see output that begins like the following run domsrc Running DOMSrcExample Body contents Content jis Name is urn uddi org api_v2 businessList Attribute name is generic Attribute value is 2 0 Attribute name is operator Attribute value is www ibm com services uddi Attribute name is truncated Attribute value is false Attribute name is xmlns Attribute value is urn uddi org api_v2 If you run DOMSrcExample with the file uddimsg xm1 or slide xml you will see runtime errors Attachments java The example Attachments java based on the code fragments in the sections Creating an AttachmentPart Object and Adding Content page 137 and Access ing an AttachmentPart Object page 139 creates a message that has a text attachment and an image attachment It then retrieves the contents of the attach ments and prints the contents of the text attachment You will find the code for Attachments in the following directory lt INSTALL gt javaeetutorial5 examples saaj attachments src Attachments first creates a message in the usual way It then creates an Attach mentP
261. ry by calling the following line of code XMLSignatureFactory factory XMLSignatureFactory getInstance DOM 224 JAVA XML DIGITAL SIGNATURE API We then invoke the unmarshalXMLSignature method of the factory to unmar shal an XMLSignature object and pass it the validation context we created ear lier XMLSignature signature factory unmarshalXMLSignature valContext Validating the XML Signature Now we are ready to validate the signature We do this by invoking the validate method on the XMLSignature object and pass it the validation context as fol lows boolean coreValidity signature validate valContext The validate method returns true if the signature validates successfully according to the core validation rules in the W3C XML Signature Recom mendation and false otherwise What If the XML Signature Fails to Validate If the XMLSignature validate method returns false we can try to narrow down the cause of the failure There are two phases in core XML Signature validation e Signature validation the cryptographic verification of the signature e Reference validation the verification of the digest of each reference in the signature Each phase must be successful for the signature to be valid To check if the sig nature failed to cryptographically validate we can check the status as follows boolean sv Signature getSignatureValue validate valContext System out printInC signature validat
262. s This allows for robust evolution ensuring that a change in semantics will not be silently ignored by those who may not fully understand it If the actor for a header that has a mustUnderstand attribute set to true cannot process the header it must send a SOAP fault back to the sender See Using SOAP Faults page 145 The actor must not change state or cause any side effects so that to an outside observer it appears that the fault was sent before any header processing was done For example you could set the mustUnderstand attribute to true for the con firmationHeader in the code fragment in The Actor Attribute page 141 QName confirmation new QName nameSpaceURI confirmationDesk nameSpace SOAPHeaderElement confirmationHeader header addHeaderElement confirmation confi rmationHeader setActor http gizmos com confirmations confi rmationHeader setMustUnderstand true This fragment produces the following XML lt ns confirmationDesk xmIns ns http gizmos com NSURI SOAP ENV actor http gizmos com confirmations SOAP ENV mustUnderstand 1 gt USING SOAP FAULTS 145 You can use the getMustUnderstand method to retrieve the value of the must Understand attribute For example you could add the following to the code fragment at the end of the preceding section System out printInC mustUnderstand is headerElement getMustUnderstand The relay Atinbute The SOAP 1 2 specification adds a
263. s Interoperability Organization WS I web site WS I is an open industry organization chartered to promote Web services interoperability across platforms operating systems and programming lan guages Specifically WS I creates promotes and supports generic protocols for the interoperable exchange of messages between Web services WS I creates profiles which recommend what to use and how to use it from the various web services specifications created by W3C OASIS and the JCP WS I is working on the following profiles related to web services security The profiles can be viewed from the WS I web site at http ww ws i org deliverables Default aspx e Basic Security Profile BSP 239 240 SECURING WEB SERVICES The Basic Security Profile provides guidance on the use of WS Security and the User Name and X 509 security token formats e REL Token Profile The REL Token Profile is the interoperability profile for the Rights Expression Language REL security token that is used with WS Secu rity e SAML Token Profile This is the interoperability profile for the Security Assertion Markup Lan guage SAML security token that is used with WS Security e Security Challenges Threats and Countermeasures This document identifies potential security challenges and threats in a web service application and identifies appropriate candidate technologies to address these challenges The section Security Challenges Threats and Countermeasures
264. s W3C XML Schema default If you do not specify this switch your input schemas will be treated as W3C XML Schema 18 USING JAXB Table 3 4 xjc Command Line Options Continued Option or Argument Description Suppress compiler output such as progress information and warn quiet ings help Display a brief summary of the compiler switches version Display the compiler version information Xlocator Enable source location support for generated code Xsync methods Generate accessor methods with the synchronized keyword Mark the generated code with the javax annotation Gener mark generated ated annotation J AXB Schema Generator Options The JAXB Schema Generator schemagen creates a schema file for each namespace referenced in your Java classes The schema generator can be launched using the appropriate schemagen shell script in the bin directory for your platform The schema generator processes Java source files only If your Java sources reference other classes those sources must be accessible from your system CLASSPATH environment variable or errors will occur when the schema is generated There is no way to control the name of the generated schema files You can display quick usage instructions by invoking the scripts without any options or with the help switch The syntax is as follows schemagen options java_source_files The schemagen command line options are listed
265. s intended for programmers who are interested in developing and deploying Web services and Web applications on the Sun Java System Applica tion Server Platform Edition 9 Prerequisites Before proceeding with this tutorial you should have a good knowledge of the Java programming language A good way to get to that point is to work through all the basic and some of the specialized trails in The Java Tutorial Mary Campione et al Addison Wesley 2000 In particular you should be familiar ABOUT THIS TUTORIAL with relational database and security features described in the trails listed in Table 1 Table 1 Prerequisite Trails in The Java Tutorial JDBC http java sun com docs books tutorial jdbc Security http java sun com docs books tutorial securityl 2 How to Use This Tutonal The Java Web Services Tutorial addresses the following technology areas e The Java Architecture for XML Web Services JAX WS e The Java Architecture for XML Binding JAXB e The StAX APIs and the Sun Java Streaming XML Parser implementation e SOAP with Attachments API for Java SAAJ e The Java Architecture for XML Registries e XML Digital Signature e Security in the Web Tier All of the examples for this tutorial except for the XML Digital Signature exam ples are installed with the Java Web Services Tutorial for Java WSDP 2 0 bun dle and can be found in the subdirectories of the lt jwstutorial20 gt samples lt technology gt
266. s oasis open org wss 2004 01 0asis 200401 wss soap message security 1 0 Base64Binary valueType http docs oasis open org wss 2004 Q1 o0asis 200401 wss x509 token profi le 1 0 X509SubjectKeyIdentifier certificateAlias xws security client keyReferenceType Identifier gt lt xwss Sign gt lt xwss SecurityConfiguration gt lt xwss Service gt lt xwss SecurityEnvi ronmentHandler gt simple client SecurityEnvironmentHandler lt xwss SecurityEnvi ronmentHand1er gt lt xwss JAXRPCSecurity gt For more information on writing and understanding security configura tions and setting up SecurityEnvironmentHandlers please see the Java Web Services Developer Pack Tutorial at http java sun com web services docs 1 6 tutorial doc index htm1 2 In your client code create an XWSSecurityConfiguration object initial ized with the security configuration generated Here is an example of the code that you would use in your client file For an example of a complete file that uses this code look at the example client in the jaxws2 0 sim ple doclit src simple client directory FileInputStream f new FileInputStream etc client_security_config xm1 XWSSecurityConfiguration config SecurityConfigurationFactory newxXwSSecurityConfiguration Cf 3 Set security configuration information on the RequestContext by using the XwSSecurityConfiguration MESSAGE_SECURITY_CONFIGURATION property For an example of a co
267. s server log In the server log you will find the output from the executePublish and exe cuteQuery methods wrapped in logging information After you run the example use the following command to undeploy the applica tion asant undeploy ear You can use the run delete target in the simple directory to delete the organi zation that was published Further Information For more information about JAXR registries and web services see the follow ing e Java Specification Request JSR 93 JAXR 1 0 http jcp org jsr detail 093 jsp e JAXR home page FURTHER INFORMATION 211 http java sun com xml jaxr Universal Description Discovery and Integration UDDD project http www uddi org ebXML http www ebxml org Service Registry ebXML Registry Repository http www sun com products soa registry Open Source JAXR Provider for ebXML Registries http ebxmlrr sourceforge net jaxr Java Platform Enterprise Edition http java sun com javaee Java Technology and XML http java sun com xm1 Java Technology and Web Services http java sun com webservices 212 JAVA API FOR XML REGISTRIES 7 Java XML Digital Signature API Tue Java XML Digital Signature API is a standard Java API for generating and validating XML Signatures This API was defined under the Java Commu nity Process as JSR 105 see http jcp org en jsr detail id 105 This JSR is final and this release of Java WSDP contains an FCS acce
268. s that are beneficial in many cases some of these include e StAX enabled clients are generally easier to code than SAX clients While it can be argued that SAX parsers are marginally easier to write StAX parser code can be smaller and the code necessary for the client to interact with the parser simpler e StAX is a bidirectional API meaning that it can both read and write XML documents SAX is read only so another API is needed if you want to write XML documents e SAX is a push API whereas StAX is pull The trade offs between push and pull APIs outlined above apply here STAX API Table 4 1 synopsizes the comparative features of StAX SAX DOM and TrAX table adapted from Does StAX Belong in Your XML Toolbox http www developer com xml1 article php 3397691 by Jeff Ryan Table 4 1 XML Parser API Feature Summary API Type Pull streaming Push streaming In memory tree XSLT Rule Ease of Use High Medium High Medium XPath Capability No No Yes Yes CPU and Memory Efficiency Varies Forward Only No Read XML Write XML Create Read Update Delete StAX API The StAX API exposes methods for iterative event based processing of XML documents XML documents are treated as a filtered series of events and infoset states can be stored in a procedural fashion Moreover unlike SAX the StAX API is bidirectional enabling both reading and writing of XML documents The StAX
269. s the message content If there is a SOAPFault object see Using SOAP Faults page 145 it must be in the SOAPBody object SOAPMessage an XML document SOAPEnvelope SOAPHeader OLLE Header Header SOAPBody a XML Content or SOAPFault Figure 5 1 SOAPMessage Object with No Attachments Messages with Attachments A SOAP message may include one or more attachment parts in addition to the SOAP part The SOAP part must contain only XML content as a result if any of the content of a message is not in XML format it must occur in an attachment part So if for example you want your message to contain a binary file your message must have an attachment part for it Note that an attachment part can contain any kind of content so it can contain data in XML format as well Figure 5 2 shows the high level structure of a SOAP message that has two attachments MESSAGES SOAPMessage an XML document SOAPEnvelope SOAPHeader optional Headers if any SOAPBody XML Content or SOAPFault MIME Headers i Content XML or non XML MIME Headers Content XML or non XML Figure 5 2 SOAPMessage Object with Two AttachmentPart Objects The SAAJ API provides the AttachmentPart class to represent an attachment part of a SOAP message A SOAPMessage object automatically has a SOAPPart object and its required subelements but because AttachmentPart objects are optional you must create and add them yourself Th
270. s to set the method that resolves resources during XML processing An application sets the interface on XMLIn putFactory which then sets the interface on all processors created by that fac tory instance Attributes and Namespaces Attributes are reported by a StAX processor using lookup methods and strings in the cursor interface and Attribute and Namespace events in the iterator inter face Note here that namespaces are treated as attributes although namespaces are reported separately from attributes in both the cursor and iterator APIs Note also that namespace processing is optional for StAX processors See the StAX specification for complete information about namespace binding and optional namespace processing 91 92 STREAMING API FOR XML Enor Reporting and Exception Handling All fatal errors are reported by way of javax xml stream XMLStreamExcep tion All nonfatal errors and warnings are reported using the javax xm l stream XMLReporter interface Reading XML Steams As described earlier in this chapter the way you read XML streams with a StAX processor and more importantly what you get back varies significantly depending on whether you are using the StAX cursor API or the event iterator API The following two sections describe how to read XML streams with each of these APIs Using XMLStreamReader The XMLStreamReader interface in the StAX cursor API lets you read XML streams or documents in a forward direction onl
271. sage protection policies of the enabled providers select the Providers tab 11 Select a provider for which to modify message protection policies For more description on each of the fields on the Edit Provider Configuration page select Help from the Admin Console 12 Click Save and restart the Application Server if so indicated Configuring Application Spec ific Message Sec urity Application specific web services message security functionality is configured at application assembly by adding message security binding elements to the web service endpoint The message security binding elements are added to the runtime deployment descriptors of the application sun ejb jar xm sun web xml or sun application client xm1 These message security binding elements are used to associate a specific provider or message protection policy with a web services endpoint or service reference and may be qualified so that they apply to a specific port or method of the corresponding endpoint or ref erenced service The following is an example of a sun ejb jar xm1 deployment descriptor file to which a message security binding element has been added lt sun ejb jar gt lt enterprise beans gt lt unique id gt 1 lt unique id gt lt ejb gt lt ejb name gt Hel loWorld lt ejb name gt lt jndi name gt Hel loWorld lt jndi name gt lt webservice endpoint gt lt port component name gt Hel loIF lt port component name gt lt endpoint address uri gt s
272. se writer add event writer flushQ Creating a Witter The final step is to create a stream writer in the form of a new Character event Characters getNewCharactersEvent Characters event ifCevent getData equalsIgnoreCase Namel return m_eventFactory createCharacters Calendar getInstance getTime toStringQ else return the same event else return event Running the Sample When you run the EventProducerConsumer sample the class is compiled and the XML stream is parsed as events and written back to STDOUT lt xml version 1 0 encoding UTF 8 gt lt BookCatalogue xmIns http www publishing org gt lt Book gt lt Title gt Yogasana Vijnana the Science of Yoga lt Title gt lt Author gt Dhirendra Brahmachari lt Author gt lt Date gt 1966 lt Date gt lt ISBN gt 81 40 34319 4 lt ISBN gt lt Publisher gt Dhirendra Yoga Publications lt Publisher gt lt Cost currency INR gt 11 50 lt Cost gt lt Book gt lt Book gt lt Title gt The First and Last Freedom lt Title gt lt Author gt J Krishnamurti lt Author gt lt Date gt 1954 lt Date gt lt ISBN gt 0 06 064831 7 lt ISBN gt 114 STREAMING API FOR XML lt Publisher gt Harper amp amp Row lt Publisher gt lt Cost currency USD gt 2 95 lt Cost gt lt Book gt lt BookCatalogue gt writer Sample Cursonviterjava Located in the lt javaee tutorial home gt examples stax writer directory CursorWriter j
273. sites How to Use This Tutorial About the Examples Required Software xi Building the Examples xi How to Print This Tutorial Typographical Conventions Feedback Building Web Services with J AX WS Setting the Port Creating a Simple Web Service and Client with JAX WS Requirements of a JAX WS Endpoint Coding the Service Endpoint Implementation Class Building the Service Packaging and Deploying the Service A Simple JAX WS Client Types Supported by JAX WS Web Services Interoperability and JAX WS Further Information xiii xiii xiv xvi xvi xviii XIX XIX XX xxi xxiii xxiii xxiv Binding between XML Schema and Java Classes 1 JAXB Architecture Architectural Overview The JAXB Binding Process More About Unmarshalling More About Marshalling RB wWNH iii Chapter 3 CONTENTS More About Validation Representing XML Content Java Representation of XML Schema Binding XML Schemas Simple Type Definitions Default Data Type Bindings Customizing JAXB Bindings Schema to Java Java to Schema CWFDUMN MH FS Using AMB eho ede teec ence dl General Usage Instructions 12 Description 12 Using the Examples 15 Configuring and Running the Samples 15 JAXB Compiler Options 16 JAXB Schema Generator Options 18 About the Schema to Java Bindings 19 Schema Derived JAXB Classes 22 Basic Examples 29 Unmarshal Read Example 29 Modify Marshal Example 31 Unmarshal Validate Example 33 Customizing JAXB Bindings 35
274. ss implementa tion of the Final version of the APIs XML Signatures can be applied to data of any type XML or binary see http www w3 org TR xmldsig core The resulting signature is represented in XML An XML Signature can be used to secure your data and provide data integrity message authentication and signer authentication After providing a brief overview of XML Signatures and the XML Digital Sig nature API this chapter presents two examples that demonstrate how to use the API to validate and generate an XML Signature This chapter assumes that you have a basic knowledge of cryptography and digital signatures The API is designed to support all of the required or recommended features of the W3C Recommendation for XML Signature Syntax and Processing The API is extensible and pluggable and is based on the Java Cryptography Service Pro vider Architecture The API is designed for two types of developers e Java programmers who want to use the XML Digital Signature API to gen erate and validate XML signatures 213 214 JAVA XML DIGITAL SIGNATURE API e Java programmers who want to create a concrete implementation of the XML Digital Signature API and register it as a cryptographic service of a JCA provider see http java sun com j2se 1 4 2 docs guide security CryptoSpec html Provider How XWS Sec unty and XML Digital Signature API Are Related Before getting into specifics it is important to see how XWS Security and XM
275. st java to be runnable the second argument supplied to the call method would have to be a valid existing URI and this is not true in this case However the application in the next section is one that you can run MyUddiPing java The program MyUddiPing java is another example of a SAAJ client applica tion It sends a request to a Universal Description Discovery and Integration UDDI service and gets back the response A UDDI service is a business regis try from which you can get information about businesses that have registered themselves with the registry service For this example the MyUddiPing applica tion is accessing a test demo version of a UDDI service registry Because of this the number of businesses you can get information about is limited Never theless MyUddiPing demonstrates a request being sent and a response being received Setting Up The MyUddiPing example is in the following directory lt INSTALL gt javaeetutorial5 examples saaj myuddiping Note lt INSTALL gt is the directory where you installed the tutorial bundle In the myuddiping directory you will find three files and the src directory The src directory contains one source file MyUddiPing java 154 SOAP WITH ATTACHMENTS API FOR JAVA The file build xm1 is the asant build file for this example The file build properties defines one property The file uddi properties contains the URL of the destination a UDDI test reg istry To install th
276. st stock price for Sun Microsystems which you will retrieve in the next section A connection uses a fair amount of resources so it is a good idea to close a con nection as soon as you are finished using it connection close Getting the Content of a Message The initial steps for retrieving a message s content are the same as those for giv ing content to a message Either you use the Message object to get the SOAPBody object or you access the SOAPBody object through the SOAPPart and SOAPEnve lope objects Then you access the SOAPBody object s SOAPBodyElement object because that is the element to which content was added in the example In a later section you will see how to add content directly to the SOAPPart object in which case you would not need to access the SOAPBodyElement object to add content or to retrieve it To get the content which was added with the method SOAPElement addText Node you call the method Node getValue Note that getValue returns the value of the immediate child of the element that calls the method Therefore in the fol lowing code fragment the getValue method is called on bodyElement the ele ment on which the addTextNode method was called ADDING CONTENT TO THE HEADER 133 To access bodyElement you call the getChildElements method on soapBody Passing bodyName to getChildElements returns a java util Iterator object that contains all the child elements identified by the Name object bodyNam
277. stIterator nextQ The next element in the hierarchy is a single businessInfos element so the code retrieves this element in the same way it retrieved the businessList Chil dren of SOAPBodyElement objects and all child elements from this point forward are SOAPElement objects Iterator businessInfosIterator businessList getChildElements new QName urn uddi org api_v2 businessInfos SOAPElement businessInfos CSOAPElement businessInfosIterator next Q The businessInfos element contains zero or more businessInfo elements If the query returned no businesses the code prints a message saying that none were found If the query returned businesses however the code extracts the name and optional description by retrieving the child elements that have those names The method Iterator hasNext can be used in a while loop because it returns true as long as the next call to the method next will return a child ele ment Accordingly the loop ends when there are no more child elements to retrieve Iterator businessInfolterator businessInfos getChi ldElements soapFactory createName businessInfo urn uddi org api_v2 if businessInfoIterator hasNext Q System out printIn No businesses found matching the name args 1 else MYUDDIPING JAVA 159 while businessInfolterator hasNext SOAPElement businessInfo CSOAPElement businessInfolIterator nextQ Iterator nameIterator busin
278. syntax is as follows xjc options lt schema gt The xjc command line options are listed in Table 3 4 Table 3 4 xjc Command Line Options Option or Argument Description Do not perform strict validation of the input schema s By default xjc performs strict validation of the source schema before process ing Note that this does not mean the binding compiler will not per form any validation it simply means that it will perform less strict validation By default the XJC binding compiler strictly enforces the rules out lined in the Compatibility chapter of the JAXB Specification In the default strict mode you are also limited to using only the binding customizations defined in the specification By using the exten sion switch you will be allowed to use the JAXB Vendor Exten sions extension JAXB COMPILER OPTIONS 17 Table 3 4 xjc Command Line Options Continued Option or Argument Description Specify one or more external binding files to process Each binding file must have its own b switch The syntax of the external binding files is extremely flexible You may have a single binding file that contains customizations for multiple schemas or you can break the customizations into multiple bindings files In addition the ordering of the schema files and binding files on the command line does not matter By default xjc will generate Java content classes in the current directory Use this opti
279. t lt nameXmlTransform gt specifies customiza tions to be applied Class Binding Declarations The lt class gt binding declaration enables you to customize the binding of a schema element to a Java content interface or a Java Element interface lt class gt declarations can be used to customize e A name for a schema derived Java interface e An implementation class for a schema derived Java content interface The syntax for lt class gt customizations is lt class name className imp Class imp Class gt lt javadoc gt lt javadoc gt lt class gt e name is the name of the derived Java interface It must be a legal Java inter face name and must not contain a package prefix The package prefix is inherited from the current value of package e implClass is the name of the implementation class for className and must include the complete package name e The lt javadoc gt element specifies the Javadoc tool annotations for the schema derived Java interface The string entered here must use CDATA or lt to escape embedded HTML tags Property Binding Declarations The lt property gt binding declaration enables you to customize the binding of an XML schema element to its Java representation as a property The scope of cus tomization can either be at the definition level or component level depending upon where the lt property gt binding declaration is specified The syntax for lt property gt cus
280. t See XML 1 0 2nd Edition for more information http www w3 org TR 2000 REC xm1 20001006 sec cdata sect Property Binding Declarations Of particular interest here is the generateIsSetMethod customization which causes two additional property methods isSetQuantity and unsetQuantity to be generated These methods enable a client application to distinguish between schema default values and values occurring explicitly within an instance docu ment For example in po xsd lt xsd complexType name Items gt lt xsd sequence gt lt xsd element name item minOccurs 1 maxOccurs unbounded gt lt xsd complexType gt lt xsd sequence gt lt xsd element name productName type xsd string gt lt xsd element name quantity default 10 gt lt xsd annotation gt lt xsd appinfo gt lt jxb property generateIsSetMethod true gt lt xsd appinfo gt lt xsd annotation gt lt xsd complexType gt lt xsd element gt lt xsd sequence gt lt xsd complexType gt The generateIsSetMethod applies to the quantity element which is bound to a property within the Items ItemType interface unsetQuantity and isSetQuantity methods are generated in the Items ItemType interface 54 USING JAXB MyDatatypeC onverter Class The lt INSTALL gt examp1es jaxb inline customize MyDatatypeConverter class shown below provides a way to customize the translation of XML datatypes to and from Java datatypes by means of a lt javaTy
281. t doTest args catch Exception e e printStackTraceQ public void doTest String args try System out printInC Retrieving the port from the following service service Hello port service getHelloPortQ System out printInC Invoking the sayHello operation on the port String name if args length gt name args Q else TYPES SUPPORTED BY JAX WS name No Name String response port sayHello name System out printInCresponse catch Exception e e printStackTraceQ Building and Running the Client To build the client you must first have deployed Hel loServiceApp as described in Packaging and Deploying the Service with asant page xx Then navigate to lt JAVA_EE_HOME gt examples jaxws simpleclient and do the following asant build The run the client do the following asant run Types Supported by J AX WS JAX WS delegates the mapping of Java programming language types to and from XML definitions to JAXB Application developers don t need to know the details of these mappings but they should be aware that not every class in the Java language can be used as a method parameter or return type in JAX WS For information on which types are supported by JAXB see Default Data Type Bindings page 6 Web Services Interoperability and J AX WS JAX WS 2 0 supports the Web Services Interoperability WS D Basic Profile Version 1 1 The WS I Basic
282. t information as an XMLEvent object even when using the cursor API Instantiating an XMLEventAllocator The first step is to create a new XMLInputFactory and instantiate an XMLEven tAl locator XMLInputFactory xmlif XMLInputFactory newInstance System out printInC FACTORY xmlif xmlif setEventAllocator new XMLEventAl locatorImp1 allocator xmlif getEventAllocator XMLStreamReader xmlr xmlif createXMLStreamReader filename new FileInputStream filename 106 STREAMING API FOR XML Creating an Event Iterator The next step is to create an event iterator int eventType xmIr getEventTypeQ whi le xmIr hasNextQ eventType xmIr nextQ Get all Book elements as XMLEvent object ifCeventType XMLStreamConstants START_ELEMENT amp amp xmlIr getLocalName equalsC Book get immutable XMLEvent StartElement event getXMLEvent xmlir asStartElement System out printInC EVENT event toStringQ Creating the Allocator Method The final step is to create the XMLEventAl locator method private static XMLEvent getXMLEvent XMLStreamReader reader throws XMLStreamException return allocator allocate reader Running the Sample When you run the CursorApproachEventObject sample the class is compiled and the XML stream is parsed and returned to STDOUT Note how the Book events are returned as strings event Sample EventParse java Located in the lt javaee tutorial home gt
283. tIdQ System out printInC Organization key was id A client can use a similar mechanism to delete concepts services and service bindings 193 194 JAVA API FOR XML REGISTRIES Using Taxonomies in J AXR Clients In the JAXR API a taxonomy is represented by a ClassificationScheme object This section describes how to use the implementation of JAXR in the Application Server to perform these tasks e To define your own taxonomies e To specify postal addresses for an organization Defning a Taxonomy The JAXR specification requires that a JAXR provider be able to add user defined taxonomies for use by JAXR clients The mechanisms clients use to add and administer these taxonomies are implementation specific The implementation of JAXR in the Application Server uses a simple file based approach to provide taxonomies to the JAXR client These files are read at run time when the JAXR provider starts up The taxonomy structure for the Application Server is defined by the JAXR Pre defined Concepts DTD which is declared both in the file jaxrconcepts dtd and in XML schema form in the file jaxrconcepts xsd The file jaxrcon cepts xml1 contains the taxonomies for the implementation of JAXR in the Application Server All these files are contained in the lt JAVAEE_HOME gt 1ib appserv ws jar file This JAR file also includes files that define the well known taxonomies used by the implementation of JAXR in the Application
284. ted in the lt javaee home gt 1ib directory Included with this J2EE tutorial are StAX code samples located in the lt jav aee tutorial home gt examples stax directory that illustrate how Sun s SJSXP implementation works These samples are described in the Sample Code section later in this chapter Before proceeding with the sample code there are two important aspects of the SJSXP about which you should be aware e Reporting CDATA Events e SJSXP Factories Implementation These two topics are discussed below Reporting CDATA Events The javax xml stream XMLStreamReader implemented in the SJSXP does not report CDATA events If you have an application that needs to receive such events configure the XMLInputFactory to set the following implementation specific report cdata event property XMLInputFactory factory XMLInptuFactory newInstance factory setProperty report cdata event Boolean TRUE 97 98 STREAMING API FOR XML SJ SXP Factories Implementation Most applications do not need to know the factory implementation class name Just adding the javaee jar and appserv ws jar files to the classpath is suffi cient for most applications because these two jars supply the factory implemen tation classname for various SJSXP properties under the META INF services directory for example javax xml1 stream XMLInputFactory javax xm l stream XMLOutputFactory and javax xml stream XMLEvent Factory which is the
285. tem out public static void displayItems Items items the items object contains a List of primer po ItemType objects List itemTypeList items getItemQ 10 Walking of the Items branch is iterated until all items have been printed for Iterator iter itemTypeList iteratorQ iter hasNextQ Items ItemType item Items ItemType iter next System out printin t item getQuantity copies of item getProductName V O Sample Output Running java Main for this example produces the following output Ship the following items to Alice Smith 123 Maple Street Cambridge MA 12345 US 5 copies of Nosferatu Special Edition 1929 3 copies of The Mummy 1959 3 copies of Godzilla and Mothra Battle for Earth Godzilla vs King Ghidora Modify Marshal Example The purpose of the Modify Marshal example is to demonstrate how to modify a Java content tree 1 The lt INSTALL gt examples jaxb modify marshal Main java class declares imports for three standard Java classes plus four JAXB binding framework classes and primer po package import java io FileInputStream import java io IOException 32 USING JAXB import java math BigDecimal import javax xml bind JAXBContext import javax xml bind JAXBException import javax xml bind Marshaller import javax xml bind Unmarshal ler import primer po 2 A JAXBContext instance is created for handling classes generated in primer po JAX
286. ter interface In class KitchenWorldBasket the XmlJavaTypeAdapter annotation is used to pair AdapterPurchaseListToHashMap with field HashMap basket This pairing will cause the marshal unmarshal method of AdapterPurchaseListToHashMap to be called for any corresponding marshal unmarshal action on KitchenWor1d Basket j2s xmlAtinbute feld Example The j2s xmlAttribute field example shows how to use the XmlAttribute anno tation to define a property or field to be treated as an XML attribute The XmlAttribute annotation maps a field or JavaBean property to an XML attribute The following rules are imposed e A static final field is mapped to a XML fixed attribute e When the field or property is a collection type the items of the collection type must map to a schema simple type e When the field or property is other than a collection type the type must map to a schema simple type When following the JavaBean programming paradigm a property is defined by a get and set prefix on a field name int zip public int getZip return zip public void setZip Cint z zip z Within a bean class you have the choice of setting the XmlAttribute annota tion on one of three components the field the setter method or the getter method If you set the XmlAttribute annotation on the field the setter method will need to be renamed or there will be a naming conflict at compile time If you set the XmlAttribute annotationt on o
287. test version of the file Note Before you compile any of the examples follow the preliminary setup instructions in Building the Examples page xxxiii Compiling the Examples To compile the programs go to the lt INSTALL gt javaeetutorial5 examples jaxr simple directory A build xml file allows you to use the following com mand to compile all the examples asant This command uses the default target build which performs the compilation The asant tool creates a subdirectory called build Running the Examples You must start the Application Server in order to run the examples against the Registry Server 201 202 JAVA API FOR XML REGISTRIES Running the J AXRPublish Example To run the JAXRPublish program use the run publish target with no com mand line arguments asant run publish The program output displays the string value of the key of the new organization After you run the JAXRPublish program but before you run JAXRDelete you can run JAXRQuery to look up the organization you published Running the J AXRQuery Example To run the JAXRQuery example use the asant target run query Specify a query string argument on the command line to search the registry for organi zations whose names contain that string For example the following command line searches for organizations whose names contain the string coffee searching is not case sensitive asant Dquery string coffee run query Running the
288. the develop ment convergence and adoption of e business standards OASIS is working on the following specifications related to web services security At the time this document was written OASIS standards documents are available from http Wwww oasis open org specs index php e Web Services Security WSS SOAP Message Security This specification describes enhancements to SOAP messaging to provide message integrity message confidentiality and message authentication while accommodating a wide variety of security models and encryption technologies This specification also defines an extensible general pur pose mechanism for associating security tokens with message content as 237 238 SECURING WEB SERVICES well as how to encode binary security tokens a framework for XML based tokens and how to include opaque encrypted keys e Security Assertion Markup Language SAML The SAML specification defines an XML based mechanism for securing Business to Business B2B and Business to Consumer B2C e com merce transactions SAML defines an XML framework for exchanging authentication and authorization information SAML uses XML encoded security assertions and XML encoded request response protocol and specifies rules for using assertions with standard transport and messaging frameworks SAML provides interoperability between disparate security systems SAML can be applied to facilitate three use cases single sign on distributed trans
289. the message also must add the attachment to itself after content has been added The SOAP Message class has three methods for creating an AttachmentPart object The first method creates an attachment with no content In this case an Attach mentPart method is used later to add content to the attachment AttachmentPart attachment message createAttachmentPartQ You add content to attachment by using the AttachmentPart method setCon tent This method takes two parameters a Java Object for the content and a String object for the MIME content type that is used to encode the object Con tent in the SOAPBody part of a message automatically has a Content Type header with the value text xm1 because the content must be in XML In contrast the type of content in an AttachmentPart object must be specified because it can be any type Each AttachmentPart object has one or more MIME headers associated with it When you specify a type to the setContent method that type is used for the header Content Type Note that Content Type is the only header that is required You may set other optional headers such as Content Id and Content Location For convenience SAAJ provides get and set methods for the head ers Content Type Content Id and Content Location These headers can be helpful in accessing a particular attachment when a message has multiple attach ments For example to access the attachments that have particular headers you can call the
290. third attribute to a SOAPHeaderElement relay This attribute like mustUnderstand is a boolean value If it is set to true it indicates that the SOAP header block must not be processed by any node that is targeted by the header block but must only be passed on to the next tar geted node This attribute is ignored on header blocks whose mustUnderstand attribute is set to true or that are targeted at the ultimate receiver which is the default The default value of this attribute is false For example you could set the relay element to true for the bi 1ingHeader in the code fragment in The Actor Attribute page 141 also changing setActor to setRole QName billing new QName nameSpaceURI billingDesk nameSpace SOAPHeaderElement billingHeader header addHeaderElement billing billingHeader setRoleC http gizmos com billing billingHeader setRelay true This fragment produces the following XML lt ns billingDesk xmIns ns http gizmos com NSURI env relay true env role http gizmos com billing gt To display the value of the attribute call getRelay System out printInC relay is headerElement getRelay Q Using SOAP Faults In this section you will see how to use the API for creating and accessing a SOAP fault element in an XML message 146 SOAP WITH ATTACHMENTS API FOR JAVA Overview of SOAP Faults If you send a message that was not successful for some reason you may get back a response
291. to access the JAXR provider The JAXR provider in turn accesses a registry The Application Server supplies a JAXR provider for UDDI registries JAXR API Registry specific Capability specific Interfaces JAXR Provider Diverse Registries ebXML Provider UDDI Provider Other Provider Figure 6 1 JAXR Architecture Implementng a J AXR Client This section describes the basic steps to follow in order to implement a JAXR client that can perform queries and updates to a UDDI registry A JAXR client is a client program that can access registries using the JAXR API This section cov ers the following topics e Establishing a connection e Querying a registry e Managing registry data e Using taxonomies in JAXR clients This tutorial does not describe how to implement a JAXR provider A JAXR pro vider provides an implementation of the JAXR specification that allows access to ESTABLISHING A CONNECTION an existing registry provider such as a UDDI or ebXML registry The implemen tation of JAXR in the Application Server itself is an example of a JAXR pro vider The Application Server provides JAXR in the form of a resource adapter using the Java EE Connector architecture The resource adapter is in the directory lt JAVAEE_HOME gt 1lib install applications jaxr ra lt JAVAEE_HOME gt is the directory where the Application Server is installed This tutorial includes several client examples which are described in Running the Clie
292. to give you some terminology and a framework for the explanations and code examples that are presented in the tutorial section The overview looks at SAAJ from two perspectives messages and connections Messages SAAJ messages follow SOAP standards which prescribe the format for mes sages and also specify some things that are required optional or not allowed With the SAAJ API you can create XML messages that conform to the SOAP 1 1 or 1 2 specification and to the WS I Basic Profile 1 1 specification simply by making Java API calls The Structure of an XML Document An XML document has a hierarchical structure made up of elements subele ments subsubelements and so on You will notice that many of the SAAJ classes and interfaces represent XML elements in a SOAP message and have the word element or SOAP or both in their names An element is also referred to as a node Accordingly the SAAJ API has the interface Node which is the base class for all the classes and interfaces that rep MESSAGES resent XML elements in a SOAP message There are also methods such as SOAPElement addTextNode Node detachNode and Node getValue which you will see how to use in the tutorial section What Is in a Message The two main types of SOAP messages are those that have attachments and those that do not Messages with No Attachments The following outline shows the very high level structure of a SOAP message with no attachments Except f
293. tomizations is lt property name propertyName collectionType propertyCollectionType fixedAttributeAsConstantProperty true false 1 o generateIsSetMethod true false 1 o J enableFailFastCheck true false 1 o J lt baseType gt lt baseType gt lt javadoc gt lt javadoc gt lt property gt CUSTOMIZATION OVERVIEW lt baseType gt lt javaType gt lt javaType gt lt baseType gt e name defines the customization value propertyName it must be a legal Java identifier collectionType defines the customization value propertyCollection Type which is the collection type for the property propertyCol lection Type if specified can be either indexed or any fully qualified class name that implements java util List fixedAttributeAsConstantProperty defines the customization value fixedAttributeAsConstantProperty The value can be either true false 1 or generatelIsSetMethod defines the customization value of generateIs SetMethod The value can be either true false 1 or Q enableFailFastCheck defines the customization value enableFail FastCheck The value can be either true false 1 or Please note that the JAXB implementation does not support failfast validation lt javadoc gt customizes the Javadoc tool annotations for the property s get ter method lt javaType gt Binding Declarations The lt javaType gt
294. ttempting to get an undefined property will result in a PropertyException being thrown public Object getProperty String name throws javax xml bind PropertyException return super newInstance javaContentInterface ee Set the specified property This method can only be used to set provider specific properties Attempting to set an undefined property will result in a PropertyException being thrown public void setProperty String name Object value throws javax xml bind PropertyException return super getProperty name super setProperty name value Create an instance of PurchaseOrder 3 public primer po PurchaseOrder createPurchase0rder O throws javax xml bind JAXBException return primer po PurchaseOrder newInstance primer po PurchaseOrder class es Create an instance of ItemsItemType public primer po Items ItemType createItemsItemType throws javax xml bind JAXBException return primer po Items ItemType newInstance primer po Items ItemType class 26 USING JAXB Create an instance of USAddress public primer po USAddress createUSAddress throws javax xml bind JAXBException return primer po USAddress newInstance primer po USAddress class Create an instance of Comment public primer po Comment createComment throws javax xml bind JAXBException return primer po Comment newInstance primer po Comm
295. un asant create war 3 Make sure the Application Server is started 4 Set your admin username and password in lt INSTALL gt javaeetutorial5 examples common bui 1ld properties 5 Run asant deploy You can view the WSDL file of the deployed service by requesting the URL http localhost 8080 hel loservice hello wsd1 ina web browser Now you are ready to create a client that accesses this service A SIMPLE JAX WS CLIENT 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 Testing the Service Without a Client The Application Server Admin Console allows you to test the methods of a web service endpoint To test the sayHello method of HelloService do the follow ing 1 Open the Admin Console by opening the following URL in a web browser http localhost 4848 Enter the admin username and password to log in to the Admin Console Click Web Services in the left pane of the Admin Console Click Hello Click Test Under Methods enter a name as the parameter to the sayHel1lo method Click the sayHel1o button This will take you to the sayHello Method invocation page NWN fF WN 8 Under Method returned you ll see the response from the endpoint A Simple J AX WS Client HelloClient is a stand alone Java program that accesses the sayHel1o method of Hel loService It makes this cal
296. urity Components XWSS calls Apache XML Security directly today in future releases it should be able to call other pluggable security providers The Apache XML Security provider and the Sun JCA Provider are both pluggable components Since JSR 105 is final today the JSR 105 layer is standard now the JSR 106 layer will be standard after that JSR becomes final 216 JAVA XML DIGITAL SIGNATURE API Package Hierarchy The six packages in the XML Digital Signature API are e javax xml crypto e javax xml crypto dsig e javax xml crypto dsig keyinfo e javax xml crypto dsig spec e javax xml crypto dom e javax xml crypto dsig dom The javax xml crypto package contains common classes that are used to per form XML cryptographic operations such as generating an XML signature or encrypting XML data Two notable classes in this package are the KeySelector class which allows developers to supply implementations that locate and option ally validate keys using the information contained in a KeyInfo object and the URIDereferencer class which allows developers to create and specify their own URI dereferencing implementations The javax xml crypto dsig package includes interfaces that represent the core elements defined in the W3C XML digital signature specification Of pri mary significance is the XMLSignature class which allows you to sign and vali date an XML digital signature Most of the XML signature structures or elements are repres
297. ust be SOAP provider id This element is optional and specifies the authentication provider used to satisfy application specific message security require ments If this attribute is not specified a default provider is used if there is one defined for the message layer If no default provider is defined authentication requirements defined in the message security bind ing element are not enforced e message security This element specifies message security require ments If the grandparent element is webservice endpoint these requirements pertain to request and response messages of the endpoint If the grandparent element is port info these requirements pertain to the port of the referenced service message This element includes the methods java method and oper ations method name to which message security requirements apply If this element is not included message protection applies to all methods request protection This element defines the authentication policy requirements of the application s request processing It has attributes of auth source and auth recipient to define what type of protection is applied and when it is applied 245 246 SECURING WEB SERVICES e response protection This element defines the authentication policy requirements of the application s response processing It has attributes of auth source and auth recipient to define what type of protection is applied and when it is applied e auth s
298. ute consists of a name for the attribute followed immedi ately by an equal sign and its value The SOAPElement interface provides methods for adding an attribute for getting the value of an attribute and for removing an attribute For example in the fol lowing code fragment the attribute named id is added to the SOAPElement object person Because person is a SOAPElement object rather than a SOAP 139 140 SOAP WITH ATTACHMENTS API FOR JAVA BodyElement object or SOAPHeaderElement object it is legal for its QName object to contain only a local name QName attributeName new QName id person addAttribute attributeName Person7 These lines of code will generate the first line in the following XML fragment lt person id Person7 gt lt person gt The following line of code retrieves the value of the attribute whose name is id String attributeValue person getAttributeValue attributeName If you had added two or more attributes to person the preceding line of code would have returned only the value for the attribute named id If you wanted to retrieve the values for all the attributes for person you would use the method getAllAttributes which returns an iterator over all the values The following lines of code retrieve and print each value on a separate line until there are no more attribute values Note that the Iterator next method returns a Java Object which is cast to a QName object so that it can be assi
299. ver When the message is sent from the initial sender it may pass through intermedi ate nodes before reaching its intended receiver In this scenario the encrypted portions continue to be opaque to any intermediate nodes and can only be decrypted by the intended receiver For this reason message layer security is also sometimes referred to as end to end security The advantages of message layer security include the following e Security stays with the message over all hops and after the message arrives at its destination e Is fine grained Can be selectively applied to different portions of a mes sage and to attachments if using XWSS e Can be used in conjunction with intermediaries over multiple hops e Is independent of the application environment or transport protocol The disadvantage to using message layer security is that it is relatively complex and adds some overhead to processing The Application Server and the Java Web Services Developer Pack Java WSDP both support message security e The Sun Java System Application Server uses Web Services Security WSS to secure messages Using WSS is discussed in Using the Applica tion Server Message Security Implementation page 242 e The Java Web Services Developer Pack Java WSDP includes XML and Web Services Security XWSS a framework for securing JAX RPC JAX WS and SAAJ applications as well as message attachments An implementation of XWSS is included in the Applic
300. ver s default mes sage security providers In this case web services are protected using default configuration files and default WSS providers e The xms_apl_1v1 application shows how to enable message layer security at the application level by modifying the runtime deployment descriptor sun ejb jar xml or sun web xm1 In this case you can selectively specify when how message layer security can be applied to a specific method or for all methods in a web service The instructions which accompany the sample describe how to enable the WS Security functionality of the Application Server such that it is used to secure the USING THE JAVA WSDP XWSS SECURITY IMPLEMENTATION xms application The sample also demonstrates the binding of WS Security func tionality directly to the application The samples directory will only exist if you selected Install Samples Server during installation The sample applications are installed in the following directories e lt INSTALL gt samples webservices security ejb apps xms e lt INSTALL gt samples webservices security ejb apps xms_ap1_lv1 For information on compiling packaging and running the sample applications refer to the sample file at lt INSTALL gt samples webservices security docs common htm1 or to the Securing Applications chapter of the Application Server Developers Guide see Further Information page 251 for a link to this docu ment Using the Java WSDP XWSS Sec unty Imple
301. vice that are supported by a specified service The JAXRQuery program illustrates how to query a registry by organization name and display the data returned The JAXRQueryByNAICSClassification and JAXRQueryByWSDLClassification programs illustrate how to query a registry using classifications All JAXR providers support at least the following taxono mies for classifications The North American Industry Classification System NAICS See http www census gov epcd www naics htm for details e The Universal Standard Products and Services Classification UNSPSC See http www eccma org unspsc for details e The ISO 3166 country codes classification system maintained by the Inter national Organization for Standardization ISO See http www 1so org iso en prods services iso3166ma index htm for details The following sections describe how to perform some common queries e Finding organizations by name e Finding organizations by classification 181 182 JAVA API FOR XML REGISTRIES e Finding services and service bindings Finding Organizations by Name To search for organizations by name you normally use a combination of find qualifiers which affect sorting and pattern matching and name patterns which specify the strings to be searched The findOrganizations method takes a col lection of findQualifier objects as its first argument and takes a collection of namePattern objects as its second argument The following
302. y one item in the infoset at a time The following methods are available for pulling data from the stream or skipping unwanted events e Get the value of an attribute e Read XML content e Determine whether an element has content or is empty e Get indexed access to a collection of attributes e Get indexed access to a collection of namespaces e Get the name of the current event if applicable e Get the content of the current event if applicable Instances of XMLStreamReader have at any one time a single current event on which its methods operate When you create an instance of XMLStreamReader on a stream the initial current event is the START_DOCUMENT state The XMLStream Reader next method can then be used to step to the next event in the stream Reading Properties Atinbutes and Namespaces The XMLStreamReader next method loads the properties of the next event in the stream You can then access those properties by calling the XMLStream Reader getLocalName and XMLStreamReader getText methods READING XML STREAMS 93 When the XMLStreamReader cursor is over a StartElement event it reads the name and any attributes for the event including the namespace All attributes for an event can be accessed using an index value and can also be looked up by namespace URI and local name Note however that only the namespaces declared on the current StartEvent are available previously declared namespaces are not maintained and redeclar
303. y limitations on this type of customization e Only simpleType definitions with enumeration facets can be customized using this binding declaration e This customization only applies to a single simpleType definition at a time To map sets of similar simpleType definitions on a global level use the typesafeEnunBase attribute in a lt globalBindings gt declaration as described Global Binding Declarations page 42 The syntax for the lt typesafeEnumClass gt customization is lt typesafeEnumClass name enumClassName lt typesafeEnumMember gt lt typesafeEnumMember gt lt javadoc gt enumClassJavadoc lt javadoc gt lt typesafeEnumClass gt e name must be a legal Java Identifier and must not have a package prefix e lt javadoc gt customizes the Javadoc tool annotations for the enumeration class e You can have zero or more lt typesafeEnumMember gt declarations embed ded in a lt typesafeEnumClass gt declaration The syntax for the lt typesafeEnumMember gt customization is lt typesafeEnumMember name enumMemberName gt value enumMemberValue lt javadoc gt enumMemberJavadoc lt javadoc gt lt typesafeEnumMember gt e name must always be specified and must be a legal Java identifier e value must be the enumeration value specified in the source schema e lt javadoc gt customizes the Javadoc tool annotations for the enumeration constant 48 USING JAXB For inline a
304. zation Namespace Prefix All standard JAXB binding declarations must be preceded by a namespace prefix that maps to the JAXB namespace URI http java sun com xm1 ns jaxb For example in this sample jxb is used To this end any schema you want to CUSTOMIZE INLINE EXAMPLE 49 customize with standard JAXB binding declarations must include the JAXB namespace declaration and JAXB version number at the top of the schema file For example in po xsd for the Customize Inline example the namespace decla ration is as follows lt xsd schema xmIns xsd http www w3 org 2001 XMLSchema xmIns jxb http java sun com xml ns jaxb jxb version 1 0 gt A binding declaration with the jxb namespace prefix would then take the form lt xsd annotation gt lt xsd appinfo gt lt jxb globalBindings binding declarations gt lt jxb schemaBindings gt binding declarations lt jxb schemaBindings gt lt xsd appinfo gt lt xsd annotation gt Note that in this example the globalBindings and schemaBindings declara tions are used to specify respectively global scope and schema scope customi zations These customization scopes are described in more detail in Scope Inheritance and Precedence page 40 Customize Inline Example The Customize Inline example illustrates some basic customizations made by means of inline annotations to an XML schema named po xsd In addition this example implements a custom datatype converter class My

The Java™ Web Services Tutorial

Contents

Download Pdf Manuals

Related Search

Related Contents

The Java&trade; Web Services Tutorial

Contents

Download Pdf Manuals

Related Search

Related Contents

The Java™ Web Services Tutorial