Home

The Java™ Web Services Tutorial

1. 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 XMLStreamwriter public void writeStartElement String localName throws XMLStreamException public void writeEndElement 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 3 2 below The primary parser interface for read ITERATOR API 93 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 nextE
2. The alias to be used to store the key entry private key ali li i ae L zalias aljas and the certificate inside the keystore keyexport 199 keyexport This tool is used to export a private key in a keystore typically of type Java Key store JKS into a file Note The exported private key is not secured with a password so it should be han dled carefully For example you can export a private key from a keystore and use it to sign certificate requests obtained through any means using other key certificate management tools These certificate requests are then sent to a certificate authority for validation and certificate generation The keyexport tool can be found in the directory lt JWSDP_HOME gt xws secu rity bin and can be run from the command line by executing keyexport sh on Unix systems or keyexport bat on Windows systems The options for this tool are listed in Table 4 43 Table 4 43 Options for keyexport tool Option Description Required The location of the file to which the private key will keyfile key file b exported This specifies the output format The options are DER and outform output for PEM The DER format is the DER encoding binary format mat of the certificate The PEM format is the base64 encoding of the DER encoding with header and footer lines added keystore keystore Location of the keystore file containing the key If no value is file given this optio
3. The Java Web Services Tutonal ForJava Web Services Developer s Pack v1 6 June 14 2005 Copyright 2005 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 DOCUMENTA
4. lt xwss JAXRPCSecurity xmIns xwss http java sun com xml ns xwss config gt lt xwss Service gt lt xwss SecurityConfiguration dumpMessages true gt lt xwss Sign gt lt xwss Encrypt gt 216 UNDERSTANDING AND RUNNING THE XWS SECURITY SAMPLE APPLICATIONS lt xwss X509Token certificateAlias Slas keyReferenceType Identifier gt lt xwss Encrypt gt lt Requirements on messages received gt lt xwss RequireEncryption gt lt xwss RequireSignature gt lt xwss SecurityConfiguration gt lt xwss Service gt lt xwss SecurityEnvi ronmentHandler gt sample SecurityEnvironmentHandler lt xwss SecurityEnvi ronmentHand1er gt lt xwss JAXRPCSecurity gt Encrypting then Signing the Request Verifying then Decrypting the Signature The security configuration pair encrypt sign client xm1 and encrypt sign server xml enable the following tasks e Client encrypts the request body then signs and sends it e Server verifies the signature and then decrypts the request body e Server sends its response The encrypt sign client xml file looks like this lt xwss JAXRPCSecurity xmIns xwss http java sun com xml ns xwss config gt lt xwss Service gt lt xwss SecurityConfiguration dumpMessages true gt lt First encrypt the contents of the soap body gt lt xwss Encrypt gt lt xwss X509Token keyReferenceType Identifier certificateAlias slas gt lt xwss Encrypt gt
5. Cambridge MA 12345 po setShipTo shipTo USAddress billTo createUSAddress Robert Smith 8 Oak Avenue Cambridge MA s 12345 po setBillTo billTo The ObjectFactory class is used to instantiate a new empty Items object Items items objFactory createItems 7 A get method is used to get a reference to the ItemType list List itemList items getItem ItemType objects are created and added to the Items list itemList add createItemType Nosferatu Special Edition 1929 new BigInteger 5 new BigDecimal 19 99 null null 242 NO itemList add createItemType The Mummy 1959 new BigInteger 3 new BigDecimal 19 98 CREATE MARSHAL EXAMPLE 49 null null 242 MU itemList add createItemType Godzilla and Mothra Battle for Earth Godzilla vs King Ghidora new BigInteger 3 new BigDecimal 27 95 null null 242 GZ 9 The items object now contains a list of ItemType objects and can be added to the po object po setItems items 10 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 createMarshallerQ m setProperty Marshaller JAXB_FORMATTED_OUTPUT Boolean TRUE m marshal po System out 11 An empty USAddress object is
6. 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 lt xsd irestriction 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 binding 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
7. java lt env Body gt java lt nsQ Ping gt java lt ns ticket gt SUNW lt ns ticket gt java lt ns text gt Hello lt ns text gt java lt nsQ Ping gt java lt env Body gt java lt env Envelope gt java Sending Message End java INFO Received Message Start java lt xml version 1 0 encoding UTF 8 gt java lt env Envelope xmIns env http 232 UNDERSTANDING AND RUNNING THE XWS SECURITY SAMPLE APPLICATIONS schemas xmlsoap org soap envelope xmIns enc http schemas xmlsoap org soap encoding xmIns nsQ http xmlsoap org Ping xmins xsd http www w3 org 2001 XMLSchema xmIns xsi http www w3 org 2001 XMLSchema instance gt java lt env Body gt java lt nsQ PingResponse gt java lt nsQ text gt Hello lt ns text gt java lt ns PingResponse gt java lt env Body gt java lt env Envelope gt java Received Message End The server code in server src sample PingImp1 java makes use of a Sub jectAccessor to access and print the authenticated Subjects principal from within the business method Ping You can view similar messages in the server logs lt SJSAS_HOME gt domains lt domain name gt logs server log lt TOMCAT_HOME gt logs launcher server 1log lt SJISWS_HOME gt lt Virtual Server Dir gt logs errors XWS Secunty APis Sample Application The focus of api sample is to demonstrate how to use XWS Security APIs to
8. 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 es Create an instance of USAddress public primer po USAddress createUSAddress throws javax xml bind JAXBException return primer po USAddress newInstance primer po USAddress class es Create an instance of Comment public primer po Comment createComment Q throws javax xml bind JAXBException return primer po Comment newInstance primer po Comment class Create an instance of Comment 3 public primer po Comment createComment String value throws javax xml bind JAXBException 40 USING JAXB 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 return primer po PurchaseOrderType newInstance primer po PurchaseOrderType class PurchaseOrderjava 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
9. The other object becomes the target object Select the Association radio button if it is not already selected 4 Type a name and description for the Association in the Details area The source and target object ID values are already filled in Choose a type value from the Association Type menu Click Save to save the Association 306 USING THE SERVICE REGISTRY WEB CONSOLE 8 Developing Clients for the Service Registry Tiss chapter describes how to use the Java API for XML Registries JAXR to access the Service Registry the Registry After providing a brief overview of JAXR and the examples described in this chapter this chapter describes how to implement a JAXR client to query the Registry and publish content to the Registry and its associated repository Overview of J AXR This section provides a brief overview of JAXR It covers the following topics e About Registries and Repositories e About JAXR e JAXR Architecture e About the Examples About Registries and Repositones 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 DEVELOPING CLIENTS FOR THE SERVICE REGISTRY loosely coupled business to business B2B interactions A registry is available to organizations as a shared resource normally in the form of a web based ser vice Currently there are a variety of specificatio
10. lt xSigroup 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 xsS i group gt BIND CHOICE EXAMPLE 85 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 setValueCint value boolean isSetValue java lang String getComment void setComment java lang String value boolean isSetComment boolean isBool void setBool boolean value boolean isSetBool Object getContent boolean isSetContent void unSetContentQ 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 86 USING JAXB 3 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 crea
11. swainterop This sample application demonstrates the Soap Messages with Attachments SwA interoperability scenarios The section Soap With Attachments Sample Applica tion provides further description of the sample application along with instructions for compiling and running the application samlinterop This sample application demonstrates support for OASIS WSS Security Asser tion Markup Language SAML Token Profile 1 0 in XWS Security The section WRITING SECURITYENVIRONMENTHANDLERS 177 SAML Sample Application provides further description of the sample applica tion along with instructions for compiling and running the application e dynamic policy This sample application demonstrates how the request and response secu rity policies can be set at runtime from the SecurityEnvironmen tHandler callback The section Dynamic Policy Sample Application provides further description of the sample application along with instructions for compiling and running the application e dynamic response This sample application demonstrates using the certificate that arrived in a signed request to encrypt the response back to the requester The section Dynamic Response Sample Application provides further description of the sam ple application along with instructions for compiling and running the application Whiting Sec untyEnvironmentHandlers The signing and encryption operations require private keys and certificates An application can obtain
12. About the Admin Tool The Service Registry Administration Tool provides a simple command line interface for common administration tasks such as adding associations to the Registry and removing objects from the Registry The tool can operate in either of two modes e In batch mode you specify one or more commands on the tool s command line e In interactive mode you enter commands in the tool s interactive shell 69 70 ADMINISTERING THE SERVICE REGISTRY In keeping with the files and folders metaphor used for RegistryObject objects in RegistryPackage objects several commands such as 1s and rm mimic both the name and the behavior of well known UNIX commands that operate on files and folders Other commands have no corresponding UNIX equivalent Starting the Admin Tool To start the Admin Tool go to the bin directory of the registry and run the reg istry admin script On a Windows system cd lt JWSDP_HOME gt registry bin admin tool options On a UNIX system cd lt JWSDP_HOME gt registry bin admin tool sh options The lt JWSDP_HOME gt location is the directory where you installed the Java WSDP To exit the Admin Tool use the quit command Batch Mode To run the Admin Tool in batch mode specify the command option on the com mand line when you start the Admin Tool For example the following command executes the 1s command java jar jwsdp 1 6 registry lib admin tool jar c
13. Caught UnmarshalException catch JAXBException je je printStackTraceQ catch IOException ioe joe printStackTrace Sample Output Running java Main for this example produces the following output DefaultValidationEventHandler ERROR 1 does not satisfy the positiveInteger type Caught UnmarshalException Validate On Demand Example The Validate On Demand example demonstrates how to validate a Java content tree at runtime On Demand Validation At any point client applications can call the Validator validate method on the Java content tree or any subtree of VALIDATE ON DEMAND EXAMPLE 53 it All JAXB Providers are required to support this operation Validation is explained in more detail in More About Validation page 11 1 The lt JWSDP_HOME gt jaxb samp1es ondemand validate Main java class declares imports for five standard Java classes plus nine JAXB Java classes and the primer po package import java io FileInputStream import java io IOException import java math BigDecimal import java math BigInteger import java util List import javax xml bind JAXBContext import javax xml bind JAXBException import javax xml bind Marshaller import javax xml bind UnmarshalException import javax xml bind Unmarshaller import javax xml bind ValidationEvent import javax xml bind ValidationException import javax xml bind Validator import javax xml bind util ValidationEventCol lector import
14. INTRODUCTION TO XML AND WEB SERVICES SECURITY messaging you have the option of either implementing a CallbackHandler or implementing the com sun xml wss SecurityEnvironment interface Once implemented the appropriate instance of the Call backHandler or SecurityEn vironment interface implementation needs to be set into an instance of com sun xml wss ProcessingContext For example code uses the XWS Security APIs refer to XWS Security APIs Sample Application The SecurityEnvi ronment interface is evolving and is subject to refinement in a later release Because information such as private keys and certificates for signing and encryp tion can be obtained in various ways looking up a keystore with an alias using the default key pairs available with the container looking up a truststore with an alias etc every callback defines a set of Request inner classes and a callback can be initialized with any of its request inner classes A tagging Request inter face is also defined within the callback to tag all Request classes For example the XWS Security configuration schema defines an xwss X5 9Token element containing an optional attribute certificateAlias When the xwss X509Token element embedded inside a xwss Sign element has a certificateAlias attribute specified as shown in the following code snippet the XWS Security run time would invoke the SecurityEnvironmentHand ler of the application with a Sig natureKeyCallback object to obtain the p
15. Indicates that a username token must be present in the incom RequireUsernameToken ing messages Indicates that the incoming messages must contain a signa RequireSignature q E ture RequireEncryption Indicates that the incoming messages must be encrypted Indicates that the incoming message must contain a SAML Paena assertion of subject confirmation type Sender Vouches SV 150 INTRODUCTION TO XML AND WEB SERVICES SECURITY Table 4 11 Sub elements of SecurityConfiguration Sub elements of SecurityConfiguration Description Specifies a list of elements on which security operations are OptionalTargets nyse j P S not required in the incoming messages but are allowed Timestamp The lt Timestamp gt element specifies that a timestamp must be sent in outgoing messages For a discussion of using the Timestamp element with the inclu deTimestamp attribute of Sign see Using Timestamp and includeTimestamp Table 4 12 provides a description of its attributes Table 4 12 Attributes of Timestamp Attributes of Timestamp Description Value in seconds after which the timestamp should be consid evan ered expired Default value is 300 Usema me Token The lt UsernameToken gt element is used when a UsernameToken should be sent with outgoing messages This UsernameToken contains the sender s user and password information Table 4 13 provides a description of its attributes Table 4 13 Attributes
16. Indicates the algorithm used for signature generation and vali SignatureMethod dation Specifies the target message part to be signed Target has Target been deprecated and is included only for backward compati bility SignatureTarget Specifies the target message part to be signed Using Timestamp and includeTimestamp The following configurations of Timestamp and the includeTimestamp attribute of the Sign element have the following effect 1 If a lt Timestamp gt element is configured a timestamp will be sent in the message 2 Ifthe includeTimestamp attribute on lt Sign gt has value true and lt Times tamp gt is not configured a timestamp with default timeout value will be sent in the message and included in the signature 3 If the includeTimestamp attribute on lt Sign gt has value true and lt Times tamp gt is configured a timestamp with the properties e g timeout spec SEMANTICS OF SECURITY CONFIGURATION FILE ELEMENTS ified on the lt Timestamp gt will be sent in the message and also be included in the signature 4 If the includeTimestamp attribute on lt Sign gt has value false a times tamp is not included in the signature Encrypt The lt Encrypt gt element is used to indicate that an encrypt operation needs to be performed on the outgoing messages Table 4 16 provides a description of its sub elements Table 4 16 Sub elements of Encrypt Sub elements of Encrypt X509Tok
17. Relevant only for lt Encrypt gt and lt RequireEncryption gt targets contentOnly If true indicates that the security operation on the target ele ment is definitely required Default value is true Relevant only for lt RequireSignature gt and lt RequireEncryption gt tar gets enforce SignatureTarget The lt SignatureTarget gt sub element is called by the lt SignatureMethod gt ele ment to identify the resource that needs to be signed If neither the lt Signature Target gt nor lt Target gt sub element are specified the default value is a target that points to the contents of the SOAP body of the message The target value is a string that specifies the object to be signed and which is specified between the lt SignatureTarget gt target_value lt SignatureTarget gt elements The XWS Security APIs Sample Application provides some examples of configuration files that use this element You can specify attachments as targets by setting the type attribute to uri and specifying the target value as cid lt part name gt which specifies the value of the Content ID CID header of the attachment When the Content ID is not know until runtime such as when auto generated CIDs are run under JAX RPC the attachment can be referenced by setting the type attribute to uri and specifying SEMANTICS OF SECURITY CONFIGURATION FILE ELEMENTS 165 the target value as attachmentRef lt part name gt where part name is the WSDL part n
18. SecurityConfiguration gt lt xwss SecurityConfiguration gt tags The complete set of child elements along with the attributes that can be placed within these elements are described informally in XWS Security Configuration File Schema The formal schema definition XSD for XWS Security Configura tion can be viewed in the appendix A XWS Security Formal Schema Definition Many example security configuration files along with descriptions each are described in Simple Sample Security Configuration Files This section describes a few of these options 135 136 INTRODUCTION TO XML AND WEB SERVICES SECURITY If you are using XWS Security under JAX RPC the first set of elements of the security configuration file contain the declaration that this file is a security con figuration file The elements that provide this declaration look like this lt xwss JAXRPCSecurity xmIns xwss http java sun com xml ns xwss config gt lt XWSS Service gt lt XWSS SecurityConfiguration gt Note If you are using X WS Security in a stand alone SAAJ environment the root element of the security configuration file is lt xwss SecurityConfiguration gt An example application that uses XWS Security in a stand alone SAAJ environment is described in XWS Security APIs Sample Application Within these declaration elements are elements that specify which type of secu rity mechanism is to be applied to the SOAP message For example to apply XML Digi
19. To run the sample applications you must edit the sample build properties file for that sample application and specify information that is unique to your system and to your installation of Java WSDP 1 6 and the Application Server or other container To edit the build properties file for the example you want to run follow these steps 1 Change to the directory for the sample application you want to run lt JWSDP_HOME gt xws security samples lt example gt 2 Copy the build properties sample file to build properties 3 Edit the build properties file checking that the following properties where applicable are set correctly for your system e javahome Set this to the directory where J2SE version 1 4 2 or higher is installed Note When running on Microsoft Windows you must escape any backslashes in the javahome jwsdp home and sjsas home properties with another backslash or use forward slashes as a path separator So for example if your Application Server installation is C Sun AppServer you must set sjsas home as follows sjsas home C Sun AppServer or sjsas home C Sun AppServer e sjsas home To specify that you are running under the Application Server set this property to the directory where the Application Server is installed and make sure there is not a comment symbol to the left of this entry If you are running under a different container set the location for its install directory under the app
20. http www w3 org 2001 04 xmlenc aes256 cbc gt lt Target gt of type Target or EncryptionTarget lt Encrypt gt lt EncryptionTarget type C qname uri xpath contentOnly C true false enforce C true false value an_appropriate_ target_identifier gt lt Transform gt lt EncryptionTarget gt lt RequireEncryption id unique_policy_identifier gt Key Bearing Token lt KeyEncryptionMethod algorithm C http www w3 org 2001 04 xmlenc rsa oaep mgflp http www w3 org 2001 04 xmlenc kw tripledes http www w3 org 2001 04 xmlenc kw aes128 http www w3 org 2001 04 xmlenc kw aes256 http www w3 org 2001 04 xmlenc rsa 1_5 gt lt DataEncryptionMethod algorithm C http ww w3 org 2001 04 xmlenc aes128 cbc http www w3 org 2001 04 xmlenc tripledes cbc http www w3 org 2001 04 xmlenc aes128 cbc http www w3 org 2001 04 xmlenc aes256 cbc gt lt Target gt of type Target and or EncryptionTarget lt RequireEncryption gt Key Bearing Token lt X509Token gt lt SAMLAssertion type HOK gt XWS SECURITY CONFIGURATION FILE SCHEMA 143 lt SymmetricKey gt lt X509Token id any_legal_id Must be unique within the resulting XML strid legal_id certificateAlias alias_SecurityEnvironment_understands keyReferencelype Direct Identifier IssuerSerialN umber encodinglype http docs oasis open org wss 2004 01
21. ity authoritylId 160 INTRODUCTION TO XML AND WEB SERVICES SECURITY Table 4 24 Attributes of RequireSAMLAssertion Continued Attributes of RequireSAMLAssertion Description Element content of the string identifier for the keyIdenti fier Indicates whether the token reference identifies a token by keyReferenceType AssertionId Identifier or by an embedded reference Embedded The default value is Identifier Indicates to use the SV type of SAML assertion The SV con firmed assertion is not contained in the message Required Optonallargets The lt OptionalTargets gt element is used when an operation is optional for a specific target Table 4 25 provides a description of its sub elements Table 4 25 Sub elements of OptionalTargets Sub elements of OptionalTargets Description Indicates that a security operation is allowed to be performed on this target but it is not required One or more of these ele ments can be specified The augmented cid syntax is not allowed as the value of the Target when Target is a sub ele ment of OptionalTargets Transform The lt Transform gt element is an optional ordered list of processing steps to be applied to the resource s content before it is digested Transforms can include operations such as canonicalization encoding decoding XSLT XPath XML schema validation or XInclude The recommendation that discusses this method is the W3C XML Signature Syntax
22. 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 getZip Q System out printIn t address getCountry n The Items list branch is walked and item information is printed to sys tem out public static void displayItems Items items the items object contains a List of primer po ItemType objects List itemTypeList items getItem 10 Walking of the Items branch is iterated until all items have been printed for Iterator iter itemTypeList iteratorQ iter hasNext MODIFY MARSHAL EXAMPLE 45 Items ItemType item Items ItemType iter next System out printin t item getQuantity copies of item getProductName Q go alae D 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
23. lt name gt Alice Smith lt name gt lt street gt 123 Maple Street lt street gt lt city gt Cambridge lt city gt lt state gt MA lt state gt lt zZip gt 12345 lt zip gt lt shipTo gt lt bi1l1To gt lt name gt Robert Smith lt name gt lt street gt 8 Oak Avenue 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 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 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 11 1 The lt JWSDP_HOME gt jaxb samples unmarshal valid
24. request setPrivateKey privKey catch Exception e throw new IOException e getMessage else throw new UnsupportedCallbackException null Unsupported Callback Type Encountered This handler uses a keystore to locate the private key and certificate pair and sets it using AliasPrivKeyCertRequest As shown in the sample code the SecurityEnvironmentHandler should throw an UnsupportedCallbackException whenever it cannot handle a Callback or a particular Request type of a Callback The type of Request with which the Callback is initialized often depends on the information specified in the security configuration file of the application For example if the xwss X509Token specified under an xwss Sign element did not contain the certificateAlias attribute XWS Security would invoke the appli cation s SecurityEnvironmentHandler with SignatureKeyCal1 back DefaultPrivKeyCertRequest to try and obtain the default private key and certificate pair If the SecurityEnvironmentHandler does not handle this request and throws an UnsupportedCallbackException the signature opera tion would fail 179 180 INTRODUCTION TO XML AND WEB SERVICES SECURITY For more information read the API documentation for callbacks from the lt JWSDP_HOME gt xws security docs api com sun xm1 wss imp1 callback package summary htm1 This documentation includes the list of mandatory and optional callbacks and the details of the Callback classes
25. ties serializers and WSDL files Note For the 2 0 release of JAX RPC JAX RPC will be renamed to JAX WS JAX WS will be part of the XWS Security 2 0 FCS later this year When this renaming occurs the wscompi le tool will be replaced and these steps and the build xml files for the sample applications will need to be modified accordingly XWS Security has been integrated into JAX RPC through the use of security configuration files The code for performing the security operations on the client and server is generated by supplying the security configuration files to the JAX RPC wscompi le tool The wscompi le tool is instructed to generate security code via the security option which specifies the security configuration file See Con figuring Security Configuration Files for more information on creating and using secu rity configuration files To use the XWS Security framework set up the client and server side infrastruc ture A critical component of setting up your system for XWS Security is to set up the appropriate database for the type of security DSig XML Enc UserName Token to be used Depending on the structure of your application these data bases could be any combination of keystore files truststore files and username password files CONFIGURING SECURITY CONFIGURATION FILES Configuring Secunty Configuration Filles XWS Security makes it simple to specify client and server side configurations describing security setting
26. 2 Store the WSDL document in the repository and create an ExtrinsicOb ject that refers to it Set the extrinsic object s type to WSDL and its mime type to text xml 3 Specify the extrinsic object as the specificationObject attribute of the Speci ficationLink object 4 Add the SpecificationLink object to the ServiceBinding object 5 Add the ServiceBinding object to the Service object 6 Save the Service object After you create a Service and ServiceBinding create a Speci ficationLink SpecificationLink specLink blcm createSpecificationLink specLink setName Spec Link Name specLink setDescription Spec Link Description STORING ITEMS IN THE REPOSITORY Create an ExtrinsicObject as described in Creating an Extrinsic Object page 60 Use the ID for the WSDL concept and the text xml MIME type String conceptid urn oasis names tc ebxml regrep ObjectType RegistryObject ExtrinsicObject WSDL Concept objectTypeConcept Concept bqm getRegistryObject conceptId CCExtrinsicObjectImp1 eo setObjectType objectTypeConcept eo setMimeType text xm1 Set the ExtrinsicObject as the specification object for the Specification Link specLink setSpecificationObject eo Add the SpecificationLink to the ServiceBinding then add the objects to their collections and save the services binding addSpecificationLink specLink serviceBindings add binding When you remove a service from the Registry
27. If you have queried the Registry without specifying a particular object type you can retrieve the type of the objects returned by the query Use the Registry0b ject getObjectType method which returns a Concept value You can then use the Concept getValue method to obtain the String value of the object type For example Concept objType object getObjectTypeQ System out printInC Object type is objType getValue The concept will be one of those in the canonical classification scheme Object Type For an example of this code see JAXRQueryByName java in Finding Objects by Name Example page 16 Retrieving the ID Values foran Object The unique identifier for an object is contained in a Key object A Key is a struc ture that contains the identifier in the form of an id attribute that is a String value To retrieve the identifier call the method RegistryObject get Key getIdQ The JAXR provider also has an implementation specific method for retrieving the logical identifier called a lid The lid is a String attribute of a Registry Object To retrieve the lid call RegistryObjectImp1 getLid The method has the following signature public java lang String getLid throws JAXRException 25 26 DEVELOPING CLIENTS FOR THE SERVICE REGISTRY For an example of the use of this method see JAXRQueryOrg java in Retrieving Organization Attributes Example page 30 Retrieving the Classifications foran Object Use the
28. It also displays the object s classifications external identifiers external links slots and audit trail Finding Objects by Type To find all objects of a specified type specify only the first argument of the BusinessQueryManagerImp1 findObjects method and optionally a collection of FindQualifier objects For example if typeString is a string whose value is either Service or service the following code fragment will find all ser vices in the Registry and sort them in alphabetical order Collection findQualifiers new ArrayListQ findQualifiers add FindQualifier SORT_BY_NAME_ASC BulkResponse response bqm findObjects typeString findQualifiers null null null null null You cannot use wildcards in the first argument to findObjects Finding Objects by Type Example For an example of finding objects by type see the example lt INSTALL gt regis try samples query object type src JAXRQueryByObjectType java To run the example follow these steps 1 Go to the directory lt INSTALL gt registry samples query object type 2 Type the following command specifying a string value ant run Dtype type_name FINDING OBJECTS BY CLASSIFICATION The program performs a case insensitive search returning all objects whose type is type_name and displaying their names descriptions and unique identifiers Specify the exact name of the type not a wildcard as in the following command line ant run Dtype federation
29. KeyEncryptionMethod_T minOccurs 0 maxOccurs 1 gt lt xs element name DataEncryptionMethod type DataEncryptionMethod_T minOccurs 0 maxOccurs 1 gt lt xs choice minOccurs 0 maxOccurs unbounded gt lt xs element name Target type Target_T minOccurs 0 maxOccurs unbounded gt lt xs element name EncryptionTarget type EncryptionTarget_T minOccurs 0 maxOccurs unbounded gt lt xs choice gt lt xs sequence gt lt xs attribute name id type id_T use optional gt lt xs complexType gt lt xs complexType name KeyEncryptionMethod_T gt lt xs attribute name algorithm use optional default http www w3 org 2001 04 xmlenc rsa oaep megf1p gt lt xs simpleType gt lt xs restriction base xs string gt lt xs enumeration value http www w3 org 2001 04 xmlenc rsa oaep mgflp gt lt xs enumeration value http www w3 org 2001 04 xmlenc rsa 1_5 gt lt xs enumeration value http www w3 org 2001 04 xmlenc kw tripledes gt lt xs enumeration value 108 A XWS SECURITY FORMAL SCHEMA DEFINITION http www w3 org 2001 04 xmlenc kw aes128 gt lt xs enumeration value http www w3 org 2001 04 xmlenc kw aes256 gt lt xs restriction gt lt xs simpleType gt lt xs attribute gt lt xs complexType gt lt xs complexType name DataEncryptionMethod_T gt lt xs attribute name algorithm use optional default http www w3 org 2001 04 xmlenc aes 128 cbc gt lt xs si
30. 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 The 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 97 98 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 a
31. Options menu to delete both the ExtrinsicObject registry object and the repository item to which it refers e Choose Delete Repository Item Only to delete the repository item and leave the ExtrinsicObject in the Registry You can then add another repos itory item The Deletion Options menu is meaningful only for extrinsic objects Creating Relationships Between Objects There are two kinds of relationships between objects references and associa tions They are both unidirectional That is each has a source object and a target object The Registry supports references called ObjectRefs between certain types of objects For example if you create a Service and a ServiceBinding you can cre ate a ServiceBinding reference from the Service to the ServiceBinding How ever you cannot create a reference from the ServiceBinding to the Service A Reference is not a registry object 303 304 USING THE SERVICE REGISTRY WEB CONSOLE An Association is a registry object and you can create an Association from any registry object to any other The Registry supports an AssociationType classifica tion scheme that includes a number of predefined association types OffersSer vice RelatedTo HasMember and so on You can also create new association types Associations between registry objects that you own are called intramural associations Associations in which you do not own one or both of the objects are called extramural associations If you
32. Support for securing attachments based on the WSS SwA Profile Draft Partial support for sending and receiving WS I Basic Security Profile BSP 1 0 compliant messages For more information about BSP read Interoperability with Other Web Services Enhancements to the SecurityConfi guration Schema from the previous release Sample programs that demonstrate using the framework Command line tools that provide specialized utilities for keystore manage ment including pkcs12import and keyexport OVERVIEW The XWS Security release contents are arranged in the structure shown in Table 4 1 within the Java WSDP release Table 4 1 XWS Security directory structure Directory Name lt JWSDP_HOME gt xws security etc Keystore files property files configuration files used for the exam ples lt JWSDP_HOME gt xws security docs Release documentation for the XWS Security framework For the latest updates to this documentation visit the web site at http java sun com webservices docs 1 6 xws security index html lt JWSDP_HOME gt xws security docs ap API documentation for the XWS Security framework lt JWSDP_HOME gt xws security lib JAR files containing the XWS Security framework implementa tion and dependent libraries lt JWSDP_HOME gt xws security sam ples Example code This release includes sample applications For more information on the samples read Are There Any Sample Applica
33. Using the SubjectAccessor API 196 Useful X WS Security Command Line Tools 197 pkcs12import 197 keyexport 199 wscompi le 200 Troubleshooting XWS Security Applications 200 vi CONTENTS Further Information 202 Chapter5 Understanding and Running the XWS Sec urity Sam ple Applic ations205 Setting Up To Use XWS Security With the Sample Applications 206 Setting System Properties 207 Configuring a JCE Provider 207 Setting Up the Application Server For the Examples 209 Setting Build Properties 210 Simple Security Configurations Sample Application 211 Plugging in Security Configurations 212 Simple Sample Security Configuration Files 213 Running the Simple Sample Application 225 JAAS Sample Application 226 JAAS Sample Security Configuration Files 227 Setting Up For the JAAS Sample 229 Running the JAAS Sample Application 230 XWS Security APIs Sample Application 232 The XWSSProcessor Interface 233 API Sample Client Code 234 The API Sample Security Configuration Files 236 Building and Running the API Sample Application 241 Soap With Attachments Sample Application 242 The SwA Interop Scenarios 242 SwA Sample Configuration Files 244 Running the SwA Sample Application 247 SAML Sample Application 249 SAML Interop Scenarios 249 SAML Interop Sample Configuration Files 251 Running the SAML Interop Sample 254 Dynamic Policy Sample Application 255 Security Configuration Files for Enabling Dynamic Policy 256 Setting Security Policies at Runtime 257
34. after finding all objects with the string Sun in their names you could iterate through the results and add each object to the package pkg addRegistryObject object A common use of packages is to organize a set of extrinsic objects A registry administrator can load a file system into the Registry storing the directories as registry packages and the files as the package contents See the Administration Guide for more information Organizing Objects Within Registry Packages Examples For examples of using registry packages see the two examples in lt INSTALL gt registry samples packages src JAXRPublishPackage java and JAXRQue ryPackage java The first example publishes a RegistryPackage object that includes all objects in the Registry whose names contain the string free The second example searches for this package and displays its contents To run the examples follow these steps 1 Go to the directory lt INSTALL gt registry samples packages 2 Type the following command CHANGING THE STATE OF OBJECTS IN THE REGISTRY ant pub pkg 3 Type the following command ant query pkg Changing the State of Objects in the Registry You add an AuditableEvent object to the audit trail of an object when you pub lish it to the Registry or when you modify it in any way See Retrieving the Audit Trail of an Object page 33 for details on these events and on how to obtain information about them Table 8 5 on page 33 describes
35. command line options 71 alias 71 command 71 create 72 debug 72 help 72 keypass 72 localdir 72 locale 72 registry 72 root 73 sqiselect 73 v 73 verbose 73 commands add association 76 cd 86 chown 87 cp 88 echo 90 help 91 Icd 92 1s 92 pwd 94 quit 94 rm 95 select 97 set 97 show 99 users 100 interface Concept interface 12 concepts adding to classification schemes 302 using to create classifications with JAXR 47 connection factories JAXR creating 8 Connection interface JAXR 3 8 connection properties JAXR examples 8 ConnectionFactory class JAXR 8 connections JAXR creating 8 setting properties 8 ContentManagementService classi fication scheme 18 copying files and folders to Regis try 88 cp command 88 create command line option 72 createAssociation method Life CycleManager interface 58 createClassification method LifeCycleManager interface 17 48 createClassificationScheme method LifeCycleManager inter face 46 createConcept method LifeCy cleManager interface 46 createExternalldentifier meth od LifeCycleManager interface 20 49 createExternalLink method LifeCycleManager interface 21 50 INDEX createExtrinsicObject method Li feCycleManager interface 60 createInternationalString method LifeCycleManager inter face 44 createKey method LifeCycleMan ager interface 45 createLocalizedString method Li feCycleManager interface
36. entity and its signing key Whether you choose type HOK or SV depends on where this token is located in the configuration file A standalone lt SAM LAssertion gt element under lt SecurityConfiguration gt should be of type SV An assertion of type HOK can appear as a child of a lt Sign gt or lt Encrypt gt element indicating the pres ence of a confirmation key that can be used for the operation Required Require Timestamp If the lt RequireTimestamp gt element is present a timestamp in the form of a wsu Timestamp element must be present in the incoming messages If the RequireTimestamp element is not specified a Timestamp is not required A timestamp specifies the particular point in time it marks You may also want to consider using a nonce which is a value that you should never receive more than once Table 4 18 provides a description of its attributes Table 4 18 Attributes of RequireTimestamp Attributes of RequireTimestamp Description id The id assigned to the timestamp The maximum number of seconds the sending clock can devi mexclockskew ate from the receiving clock Default is 60 timestampFreshness The maximum number of seconds the time stamp remains Limit valid Default is 300 156 INTRODUCTION TO XML AND WEB SERVICES SECURITY Require Usemame Token The lt RequireUsernameToken gt element is used to specify that a username token must be present in the incoming messages Table 4 19 provi
37. 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 xmldsig samples validate directory The file on which it operates 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 274 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 S
38. generated JAXB classes describe only the relation ships actually defined in the source schemas The result is highly portable XML data joined with highly portable Java code that can be used to create flexible lightweight applications and Web services This chapter describes the JAXB architecture functions and core concepts You should read this chapter before proceeding to Chapter 2 which provides sample code and step by step procedures for using JAXB BINDING XML SCHEMA TO JAVA CLASSES WITH JAXB J AXB Architecture This section describes the components and interactions in the JAXB processing model After providing a general overview this section goes into more detail about core JAXB features The topics in this section include e Architectural Overview e The JAXB Binding Process e JAXB Binding Framework e More About javax xml bind e More About Unmarshalling e More About Marshalling e More About Validation Architectural Overview Figure 1 1 shows the components that make up a JAXB implementation N XML Schema Application Code unmarshal Interfaces package and Object i mM oe javax xml bind Input 7 Binding Document Compiler 4 4 Implementation Lipeusntuden of Classes javax xml bind a XML Application Output Document Figure 1 1 JAXB Architectural Overview ARCHITECTURAL OVERVIEW As shown in Figure 1 1 a JAXB implementation comprises the following eight core compon
39. in the registry but are represented using an External Identi fier Finder methods BusinessQueryManager findClas sificationSchemes BusinessQueryManager findClassificationScheme ByName Concept Represents a taxonomy element and its structural relationship with other elements in an internal Classi ficationScheme Called a Classi ficationNode in the ebXML specifications Finder methods BusinessQueryManager findConcepts BusinessQueryManager findConceptByPath ExternalIdentifier Provides a value for the content of an external Classifica tionScheme Getter method RegistryObject getExter nalIdentifiers ExternalLink Provides a URI for content that may reside outside the registry Getter method RegistryObject getExternalLinks ExtrinsicObject Provides metadata that describes submitted content whose type is not intrinsically known to the registry and therefore must be described by means of additional attributes such as mime type No specific getter finder methods Organization Provides information about an organization May have a parent and may have one or more child organizations Always has a User object as a primary contact and may offer Service objects Finder method BusinessQueryManager findOrga nizations RegistryPackage Represents a logical grouping of registry objects A Registry Package may have any number of RegistryObjects Getter finder methods RegistryObject getRegistryPac
40. secure and validate SOAP messages in a stand alone non JAX RPC SAAJ application The XWS Security APIs can be used to secure JAX RPC applica tions too but because securing JAX RPC applications can be easily accom plished using the security configuration files this sample application focuses on securing stand alone non JAX RPC applications This sample uses configuration files that start with lt xwss SecurityConfigura tion gt as the root element as opposed to the other XWS Security samples that are based on JAX RPC and use lt xwss JAXRPCSecurity gt as the root element Documentation for XWS Security 2 0 EA APIs is located in the xws secu rity docs api directory THE XWSSPROCESSOR INTERFACE The lt JWSDP_HOME gt xws security samples api sample application demon strates the following functionality e Defines an ease of use interface XWSSProcessor interface This interface is intended to insulate API users from changes to the APIs in future releases e Provides an implementation of XwSSProcessor interface for XWS Secu rity 2 0 EA e The client com sun wss sample Client code uses the XWSSProcessor APIs to secure SOAP messages according to the security policy inferred from the SecurityConfiguration with which this XWSSProcessor was initialized e Server verifies the secured message The application prints out the client request and response SOAP messages The output from the client is sent to stdout or whichever st
41. with the binding declaration Scope Inhentance The different scopes form a taxonomy The taxonomy defines both the inherit ance and overriding semantics of customization values A customization value defined in one scope is inherited for use in a binding declaration covered by another scope as shown by the following inheritance hierarchy e A schema element in schema scope inherits a customization value defined in global scope e A schema element in definition scope inherits a customization value defined in schema or global scope e A schema element in component scope inherits a customization value defined in definition schema or global scope WHAT IS NOT SUPPORTED Similarly a customization value defined in one scope can override a customiza tion value inherited from another scope as shown below e Value in schema scope overrides a value inherited from global scope e Value in definition scope overrides a value inherited from schema scope or global scope e Value in component scope overrides a value inherited from definition schema or global scope What is Not Supported See Section E 2 Not Required XML Schema Concepts in the JAXB Specifica tion for the latest information about unsupported or non required schema con cepts J AXB APIs and Tools The JAXB APIs and tools are shipped in the jaxb subdirectory of the Java WSDP This directory contains sample applications a JAXB binding compiler xjc and imple
42. xws security etc directory For further discussion of using keystores and truststores with XWS Security applications read Keystore and Truststore Files with XWS Security Keystore and Truststore Files with XWS Sec urity For the simple sample the keystore truststore and symmetric key databases used by that example are located in the lt JWSDP_HOME gt xws security etc directory The locations of these files have been configured in the lt JWSDP_HOME gt xws security etc client security env properties and lt JWSDP_HOME gt xws security etc server security env properties files for the client and server respectively These property files are used by the Secu rityEnvironmentHandler to handle the Callbacks To plug in your own keystores and truststores for an application make sure that the certificates are of version 3 and that the client truststore contains the certifi cate of the certificate authority that issued the server s certificate and vice versa 209 210 UNDERSTANDING AND RUNNING THE XWS SECURITY SAMPLE APPLICATIONS XWS Security requires version 3 v3 certificates when the keyReferenceType attribute specified on a xwss X509Token element has a value of Identifier which indicates the use of an X 509 SubjectKeyIdenti fier extension For all other values of the keyReferenceType attribute a v1 certificate can also be used Version 3 includes requirements specified by the WSS X509 Token Profile Setting Build Properties
43. 0asis 200401 wss soap message security 1 0 Base64Binary valueType gt lt SAMLAssertion id unique_policy_identifier authorityld URI_of_Issuing_Authority strid unique_policy_identifier keyIdentifier identifier_for_Attester_Key keyReferenceType Identifier Embedded type HOK SV lt SAMLAssertion gt lt RequireSAMLAssertion id unique_policy_identifier authorityld URI_of_Issuing_Authority gt strid unique_policy_identifier type SV keyReferenceType Identifier Embedded lt Requi reSAMLAssertion gt lt SymmetricKey keyAlias alias keyname_of_a_shared_key gt keyReferenceType Direct Identifier IssuerSerialNumber Embedded EncodingType Base64Binary other wss defined encoding type ValueType token profi le specific value types lt Sign id unique_policy_identifier includeTimestamp true false gt Key Bearing Token lt CanonicalizationMethod algorithm http ww w3 org 2001 10 xm1 exc cl14n others gt 144 INTRODUCTION TO XML AND WEB SERVICES SECURITY lt SignatureMethod algorithm http www w3 org 2000 09 xmldsig rsa shal others gt lt Target gt of type Target or SignatureTarget lt Sign gt lt SignatureTarget type C qname uri xpath enforce C true false value an_appropriate_target_identifier gt lt DigestMethod algorithm C http ww w3 org 2000 09 xmldsig shal others lt Transform gt lt SignatureTarg
44. 1 pctNum setAreaCode 100 pctNum setNumber 100 1001 pctNum setTypeC Mobi lePhone Collection phoneNums new ArrayListQ phoneNums add pctNum primaryContact setTelephoneNumbers phoneNums Set primary contact email address EmailAddress emailAddress blcm createEmai lAddress jane doe TheCoffeeBreak com emai lAddress setTypeC OfficeEmail Collection emailAddresses new ArrayListQ emai lAddresses add emai lAddress primaryContact setEmai lAddresses emai lAddresses URL pcUrl new URLC Cbundle getStringC person url primaryContact setUrl pcUr Set primary contact for organization org setPrimaryContact primaryContact The telephone number type for the primary contact is the value of a concept in the PhoneType classification scheme OfficePhone MobilePhone Home Phone FAX or Beeper The email address type for the primary contact is the value of a concept in the EmailType classification scheme either Of ficeE mail or HomeEmail Creating Services and Service Bindings Most organizations publish themselves to a registry to offer services so JAXR has facilities to add services and service bindings to an organization You can also create services that are not attached to any 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 al
45. 1er implementation they supply is thread safe public class SecurityEnvironmentHandler implements CallbackHandler public void handle Callback callbacks throws IOException UnsupportedCallbackException for Cint i 0 i lt callbacks length i if Ccallbacks i instanceof PasswordValidationCallback PasswordValidationCallback cb PasswordValidationCallback callbacks i if Ccb getRequest Q instanceof PasswordValidationCal lback PlainTextPasswordReq uest setValidator for plain text password validation on callback cb else if cb getRequest instanceof PasswordValidationCal lback DigestPassword Request PasswordValidationCal lback DigestPassw ordRequest request PasswordValidationCallback DigestP asswordRequest cb getRequestQ set plaintext password on request setValidator for digest password validation on cb else throw unsupported else if callbacks i instanceof WRITING SECURITYENVIRONMENTHANDLERS 191 SignatureVerificationKeyCallback SignatureVerificationKeyCallback cb SignatureVeri ficationKeyCal lback cal1 backs i if cb getRequest instanceof SignatureVeri ficationKeyCal lback X509Su bjectKeyIdentifierBasedRequest subject keyid request SignatureVeri ficationKeyCal lback X509Su bjectKeyIdentifierBasedRequest request CSignatureVeri ficationKeyCal lback X509S ubjectKeyIdenti fierBasedRequest cb getRequest locate and setxX509Certificate on t
46. 2 4 Figure 2 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 Definition Scope Schema Scope Global Scope Figure 2 1 Customization Scope Inheritance and Precedence CUSTOMIZATION OVERVIEW Customization Syntax The syntax for the four types of JAXB binding declarations as well as the syntax for the XML to Java datatype binding declarations and the customization name space prefix are described below e Global Binding Declarations e Schema Binding Declarations e Class Binding Declarations e Property Binding Declarations e lt javaType gt Binding Declarations e Typesafe Enumeration Binding Declarations e lt javadoc gt Binding Declarations e Customization Namespace Prefix 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 0 J generateIsSetMethod true false 1 o enableFailFastCheck true false 1 o J
47. 4 SwA Scenario 4 Attachment Signature and Encryption With MIME Headers gt lt xwss Port name http xmlsoap org Ping Ping4 gt lt xwss SecurityConfiguration dumpMessages true gt 246 UNDERSTANDING AND RUNNING THE XWS SECURITY SAMPLE APPLICATIONS lt xwss Sign includeTimestamp false gt lt xwss X509Token certificateAlias xws security client gt lt xwss CanonicalizationMethod algorithm http www w3 org 2001 10 xml exc cl14n gt lt xwss SignatureMethod algorithm http www w3 org 2000 09 xmldsig rsa shal gt lt xwss SignatureTarget type uri value cid foobar gt lt xwss DigestMethod algorithm http www w3 org 2000 09 xmldsig shal gt lt xwss Transform algorithm http docs oasis open org wss 2004 XX oasis 2004XX wss swa profile 1 0 Attachment Content Onl y Trans form gt lt xwss SignatureTarget gt lt xwss Sign gt lt xwss Encrypt gt lt xwss X509Token certificateAlias slas keyReferenceType Direct gt lt xwss Target type uri conten tOnly false gt cid foobar lt xwss Target gt lt xwss Encrypt gt lt xwss SecurityConfiguration gt lt xwss Port gt lt xwss Service gt lt xwss SecurityEnvironmentHandler gt com sun xml wss sample SecurityEnvironmentHandler lt xwss SecurityEnvi ronmentHand1er gt lt xwss JAXRPCSecurity gt The security configuration file for the server is swa server xm1 Ideally each scenario would contain a RequireSignatur
48. 44 createObject method LifeCy cleManager interface 44 createOrganization method LifeCycleManager interface 51 createPersonName method Life CycleManager interface 53 createPostalAddress method LifeCycleManager interface 51 createQuery method Declara tiveQueryManager interface 35 createRegistryPackage method LifeCycleManager interface 64 createService method LifeCy cleManager interface 55 createServiceBinding method LifeCycleManager interface 55 createSlot method LifeCycleM anager interface 50 createSpecificationLink meth od LifeCycleManager interface 62 createTelephoneNumber method LifeCycleManager interface 51 createUser method LifeCycleM anager interface 53 creating registry objects 294 current directory changing 92 123 124 INDEX D database backing up and restoring 101 DataType classification scheme 18 debug command line option 72 debug property displaying value 99 setting 97 DeclarativeQueryManager inter face 4 35 DeclarativeQueryManagerImp1 class 36 DecryptionKeyCallback 183 deleteObjects method LifeCy cleManager interface 67 deleting objects from Registry Package 95 deleting registry objects 303 DeletionScopeType classification scheme 18 deprecateObjects method Life CycleManager interface 66 deprecating registry objects 302 65 example 66 descriptions of registry objects searching by 288 Details area 291 directory changing 92 displaying property values
49. 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 modify 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 To summarize using JAXB involves two discrete sets of activities e Generate and compile JAXB classes from a source schema and build an application that implements these classes e Run the application to unmarshal process validate and marshal XML content through the JAXB binding framework These two steps are usually performed at separate times in two distinct phases Typically for example there is an application development phase in which JAXB classes are generated and compiled and a binding implementation is built followed by a deployment phase in which the generated JAXB classes are used to process XML content in an ongoing live production setting Note Unmarshalling is not the only means by which a content tree may be created Schema derived content classes also support the programmatic construc
50. 7 Sub elements of Port element Indicates that what follows is security configuration for the SecurityConfiguration 4 z port This over rides any security configured for the service Indicates a port within a JAX RPC service Any including zero number of these elements may be specified Operation Operation The lt Operation gt element creates a security configuration at the operation level which takes precedence over port and service level security configurations Table 148 INTRODUCTION TO XML AND WEB SERVICES SECURITY 4 8 provides a description of its attributes Table 4 9 provides a description of its sub elements Table 4 8 Attributes of Operation Attributes of Operation Description Name of the operation as specified in the WSDL file for example name http xmlsoap org Ping PingQ Required Table 4 9 Sub elements of Operation Sub elements of Description Operation This element indicates that what follows is security configura SecurityConfiguration tion for the operation This overrides any security configured for the port and the service Sec urityC onfiguration The lt SecurityConfiguration gt element specifies a security configuration Table 4 10 provides a description of its attributes Table 4 11 provides a description of its sub elements The sub elements of SecurityConfiguration can appear in any order The order in which they appear determines the order in which they are exe
51. BSP compliant requests will be accepted BSP restrictions and rules are only applicable for those features explicitly sup ported by XWS Security For outgoing messages BSP compliant messages are created by default The only instance where BSP compliant messages are not created by default is in the case of exclusive canonicalization transform in signa tures For performance reasons this transform is not added by default but can be added explicitly to the list of transforms 133 134 INTRODUCTION TO XML AND WEB SERVICES SECURITY For incoming messages you can set the compliance attribute to bsp if you want to check for compliance in messages received from other applications or imple mentations Non compliant incoming messages are flagged when this option is set What is the XWS Sec unty Framework The XWS Security framework is used to secure JAX RPC and stand alone SAAJ applications Use XWS Security to secure SOAP messages requests and responses through signing some parts or encrypting some parts or sending username password authentication info or some combination of these Some example applications that use the technology are discussed in Are There Any Sample Applications Demonstrating XWS Security Use the XWS Security framework to secure JAX RPC applications by using the security option of the wscompile tool When you create an asant or ant target for JAX RPC clients and services the wscompi le utility generates stubs
52. BulkResponse br dqm executeQuery query Collection objects br getCollection Invoking Stored Queries Example For an example of the use of a stored query see lt INSTALL gt registry sam ples query stored src JAXRQueryStored java This example returns the user s registry login name To run the example follow these steps 1 Go to the directory lt INSTALL gt registry samples query stored 2 Type the following command ant run Querying a Registry Federation If the registry you are querying is part of one or more registry federations see About Registries and Repositories page 1 you can perform declarative queries on all registries in all federations of which your registry is a member or on all the registries in one federation To perform a query on all registries in all federations of which your registry is a member you call the implementation specific setFederated method on a Que ryImp1 object The method has the following signature public void setFederated boolean federated throws JAXRException 40 DEVELOPING CLIENTS FOR THE SERVICE REGISTRY You call the method as follows QueryImp1 query QueryImp1 dqm createQuery Query QUERY_TYPE_SQL qString query setFederated true If you know that your registry is a member of only one federation this method is the only one you need to call before you execute the query To limit your query to the registries in one federation you need to call an add
53. Digested password will be sent gt 220 UNDERSTANDING AND RUNNING THE XWS SECURITY SAMPLE APPLICATIONS lt xwss UsernameToken name Ron password noR gt lt xwss SecurityConfiguration gt lt xwss Service gt lt xwss SecurityEnvironmentHandler gt sample SecurityEnvironmentHandler lt xwss SecurityEnvi ronmentHand1er gt lt xwss JAXRPCSecurity gt Encrypt Request Body and a UserName Token The security configuration pair encrypt usernameToken client xml and encrypt usernameToken server xm enable the following tasks e Client encrypts request body e Client encrypts the UsernameToken as well before sending the request e Server decrypts the encrypted message body and encrypted UsernameTo ken e Server authenticates the user name and password against a username pass word database The encrypt usernameToken client xm1 file looks like this lt xwss JAXRPCSecurity xmIns xwss http java sun com xml ns xwss config gt lt xwss Service gt lt xwss SecurityConfiguration dumpMessages true gt lt Export a username token into the security header Assign it the mentioned wsu Id gt lt xwss UsernameToken name Ron password noR id username token gt lt xwss Encrypt gt lt xwss X509Token certificateAlias silas gt lt xwss Target type xpath gt SOAP ENV Body lt xwss Target gt lt The username token has been refered as an encryption target using a URI fragment gt
54. 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 TransformService 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 270 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
55. Final Draft for gen erating and validating XML Signatures as specified by the W3C recommenda tion It is an API that should be used by Java applications and middleware that need to create and or process XML Signatures It is used by this release of Web Services Security and can be used by non Web Services technologies for exam ple documents stored or transferred in XML Both JSR 105 and JSR 106 XML Digital Encryption APIs are core XML security components XWS Security does not use the JSR 106 APIs because currently the Java stan dards for XML Encryption are undergoing definition under the Java Community Process This Java standard is JSR 106 XML Digital Encryption APIs which you can read at http www jcp org en jsr detai1 id 106 XWS Security uses the Apache libraries for XML Encryption In future releases the goal of XWS Security is to move toward using the JSR 106 APIs Table 4 2 shows how the various technologies are stacked upon one another Table 4 2 API Implementation Stack Diagram XWS Security JSR 105 XML Signature and W3C XML Encryption Specifications W3C spec may be replaced with JSR 106 in a future release Apache XML Security implementation J2SE Security JCE JCA APIs INTEROPERABILITY WITH OTHER WEB SERVICES The Apache XML Security project is aimed at providing implementation of secu rity standards for XML Currently the focus is on the W3C standards More information on Apache XML Security
56. For links to specifications and other documents relevant to XWS Security refer to the Further Information section in Introduction to XML and Web Services Security 264 UNDERSTANDING AND RUNNING THE XWS SECURITY SAMPLE APPLICATIONS 6 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 access 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
57. Marshal example demonstrates how to use the ObjectFactory class to create a Java content tree from scratch and then marshal it to XML data 1 The lt JWSDP_HOME gt jaxb samples create marshal Main java class declares imports for four standard Java classes plus three JAXB binding framework classes and the primer po package import java math BigDecimal import java math BigInteger import java util Calendar import java util List import javax xml bind JAXBContext import javax xml bind JAXBException import javax xml bind Marshaller ke import primer po 2 A JAXBContext instance is created for handling classes generated in primer po JAXBContext jc JAXBContext newInstance primer po 3 The ObjectFactory class is used to instantiate a new empty PurchaseOr der object creating the ObjectFactory ObjectFactory objFactory new ObjectFactory 48 USING JAXB create an empty PurchaseOrder PurchaseOrder po objFactory createPurchaseOrderQ Per the constraints in the po xsd schema the PurchaseOrder object requires a value for the orderDate attribute To satisfy this constraint the orderDate is set using the standard Calendar getInstance method from java util Calendar po setOrderDate Calendar getInstanceQ The ObjectFactory is used to instantiate new empty USAddress objects and the required attributes are set USAddress shipTo createUSAddress Alice Smith 123 Maple Street
58. Name or Description of an Object e Retrieving the Type of an Object e Retrieving the ID Values for an Object e Retrieving the Classifications for an Object e Retrieving the External Identifiers for an Object e Retrieving the External Links for an Object e Retrieving the Slots for an Object e Retrieving the Attributes of an Organization or User e Retrieving the Services and Service Bindings for an Organization e Retrieving an Organization Hierarchy e Retrieving the Audit Trail of an Object e Retrieving the Version of an Object Retrieving the Name or Description of an Object The name and description of an object are both InternationalString objects An InternationalString object contains a set of LocalizedString objects The methods RegistryObject getName and RegistryObject getDescrip RETRIEVING INFORMATION ABOUT AN OBJECT tionQ return the LocalizedString object for the default locale You can then retrieve the String value of the LocalizedString object For example String name ro getName getValueQ String description ro getDescription getValue Call the getName or getDescription method with a Locale argument to retrieve the value for a particular locale Many of the examples contain private utility methods that retrieve the name description and unique identifier for an object See for example JAXRGetMy0b jects java in Finding Objects You Published Examples page 23 Retrieving the Type of an Object
59. Platform Edition 8 1 2005Q2 UR2 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 is 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 8 1 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 xi xii 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 is an adjunct to the J2EE 1 4 Tutorial which you can download from the following location http java sun com j2ee 1 4 download html tutorial The Java Web Services Tutorial addresses the following technology areas which are not covered in the J2EE 1 4 Tutorial e The Java Architecture for XML Binding JAXB e The StAX APIs and the Sun Java Streaming XML Parser implementation e XML and Web
60. Port 2 SwA Scenario 2 Encrypt Attachment Only gt lt xwss Port name http xmlsoap org Ping Ping2 gt lt xwss SecurityConfiguration dumpMessages true gt lt xwss Encrypt gt lt xwss X509Token certificateAlias slas keyReferenceType Direct gt lt xwss Target type uri gt cid foobar lt xwss Target gt lt xwss Encrypt gt lt xwss SecurityConfiguration gt lt xwss Port gt lt Port 3 SwA Scenario 3 Attachment Signature and Encryp tion gt lt xwss Port name http xmlsoap org Ping Ping3 gt lt xwss SecurityConfiguration dumpMessages true gt lt xwss Sign includeTimestamp false gt lt xwss X509Token certificateAlias xws security client gt lt xwss CanonicalizationMethod algorithm http www w3 org 2001 10 xml exc c14n gt lt xwss SignatureMethod algorithm http www w3 org 2000 09 xmldsig rsa shal gt lt xwss SignatureTarget type uri value cid foobar gt lt xwss DigestMethod algorithm http www w3 org 2000 09 xmldsig shal gt lt xwss Transform algorithm http docs oasis open org wss 2004 XX oasis 2004XX wss swa profile 1 Attachment Comp ete Transform gt lt xwss SignatureTarget gt lt xwss Sign gt lt xwss Encrypt gt lt xwss X509Token certificateAlias slas keyReferenceType Direct gt lt xwss Target type uri gt cid foobar lt xwss Target gt lt xwss Encrypt gt lt xwss SecurityConfiguration gt lt xwss Port gt lt Port
61. Postal Code 4 Click Add to close the Details Panel window The new version of the object appears in the Registry Objects area 5 Click Save in the Details area for the object Adding a Telephone Number to an Organization or User An Organization or User can have one or more telephone numbers To add a tele phone number to either an Organization or a User follow these steps 1 In the Details area for the Organization or User click the TelephoneNum bers tab The TelephoneNumbers table which may be empty appears 2 Click Add A Details Panel window opens ADDING AN EMAIL ADDRESS TO AN ORGANIZATION OR USER 299 Select a value from the Type combo box Beeper FAX HomePhone MobilePhone or OfficePhone Type values in the fields All fields except Phone Number are optional e Country Code e Area Code e Phone Number required e Extension Click Add to close the Details Panel window The new version of the object appears in the Registry Objects area Click Save in the Details area for the object Adding an Email Address to an Organization or User An Organization or User can have one or more email addresses To add an email address to either an Organization or a User follow these steps 1 In the Details area for the Organization or User click the EmailAddresses tab The EmailAddresses table which may be empty appears Click Add A Details Panel window opens Select a value
62. Queres If you expect a declarative query to return a very large result set you can use the implementation specific iterative query feature The DeclarativeQueryMan USING ITERATIVE QUERIES 37 agerImp executeQuery method can take an argument that specifies a set of parameters This method has the following signature public BulkResponse executeQuery Query query java util Map queryParams IterativeQueryParams iterativeParams throws JAXRException You can specify parameters that cause each query to request a different subset of results within the result set Instead of making one query return the entire result set you can make each individual query return a manageable set of results Suppose you have a query string that you expect to return up to 100 results You can create a set of parameters that causes the query to return 10 results at a time First you create an instance of the class IterativeQueryParams which is defined in the package org freebxml omar common The two fields of the class are startIndex the starting index of the array and maxResults the maximum number of results to return You specify the initial values for these fields in the constructor int maxResults 10 int startIndex Q IterativeQueryParams iterativeQueryParams new IterativeQueryParams startIndex maxResults Execute the queries within a for loop that terminates with the highest number of expected results and advances by the maxResults v
63. 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 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 92 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
64. RequireUsernameToken gt lt xwss SecurityConfiguration gt Building and Running the API Sample Application This sample does not require that a container be running so there is no need to start the Application Server for this example To run the api samp1e application follow these steps 1 Complete the tasks defined in the following sections of this addendum Setting System Properties Setting Build Properties 2 Modify the client configfile and server configfile properties in the build properties file so that they points to a valid security configu ration pair you want to run 3 Build and run the application from a terminal window or command prompt e On the Application Server the command to build and run the applica tion is asant run sample e On the other containers the command to build and run the application is ant run sample Note To run the sample against a remote server containing the deployed endpoint use the run remote samp 1e target in place of the run samp1e target In this situa tion make sure that the endpoint host endpoint port http proxyHost http proxyPort and service url properties are set correctly in the build prop erties file as discussed in Setting Build Properties before running the sample 242 UNDERSTANDING AND RUNNING THE XWS SECURITY SAMPLE APPLICATIONS Soap With Attachments Sample Application The swainterop sample application demonstrates the Soap with Attachments
65. Running the Dynamic Policy Sample Application 258 Dynamic Response Sample Application 260 Security Configuration Files for Enabling Dynamic Response 260 Using the CallbackHandler to Enable Dynamic Response 261 Running the Dynamic Response Sample Application 262 Further Information 263 Chapter 6 Chapter 7 CONTENTS Java XML Digital Signature API 265 How XWS Security and XML Digital Signature API Are Related 266 XML Security Stack 267 Package Hierarchy 268 Service Providers 269 Introduction to XML Signatures 270 Example of an XML Signature 270 XML Digital Signature API Examples 273 validate Example 273 genenveloped Example 278 Using the Service Registry Web Console 283 Getting Started With the Web Console 283 Starting the Web Console 284 Changing the Default Language 284 Searching the Registry 286 Using the Search Menu 286 Selecting a Query 287 Searching by Object Type 287 Searching by Name and Description 288 Searching by Classification 288 Viewing Search Results 291 Viewing Object Details 291 Using the Explore Menu 293 Publishing and Managing Registry Objects 294 Publishing Objects 294 Adding a Classification to an Object 295 Adding an External Identifier to an Object 296 Adding an External Link to an Object 296 Adding Custom Information to an Object Using Slots 297 Adding a Postal Address to an Organization or User 298 Adding a Telephone Number to an Organization or User 298 Adding an Email A
66. Simple Security Configurations Sample Application for more information on these sample appli cations UsernameToken Verification DOES XWS SECURITY IMPLEMENT ANY SPECIFICATIONS Username token verification specifies a process for sending UserNameTo kens along with the message Sending these tokens with a message binds the identity of the tokens and any other claims occurring in the security token to the message This implementation of XML and Web Services Security provides sup port for Username Token Profile which is based on OASIS WSS User name Token Profile 1 0 which can be read at http docs oasis open org wss 2004 01 o0asis 200401 wss username token pro file 1 pdf and X 509 Certificate Token Profile which is based on OASIS WSS X 509 Certificate Token Profile 1 0 which can be read at http docs oasis open org wss 2004 01 oasis 200401 wss x509 token profi le 1 0 pdf Samples containing code for sending user name and X 509 certificate tokens along with the SOAP message are included with this release in the directory lt JWSDP_HOME gt xws security samples simple Read Simple Security Configurations Sample Application for more information on these sam ple applications XWS Security Framework APIs This implementation of XML and Web Services Security provides APIs that can be used to secure stand alone Web services applications as well as JAX RPC applications These new APIs can be used to secure an out bound SO
67. Stack Figure 6 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 6 1 Java WSDP Security 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 268 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 s
68. SwA interoperability scenarios SwA describes how a web service consumer can secure SOAP attachments using XWS Security for attachment integrity confidentiality and origin authentication and how a receiver may process such a message Read more about SwA at http www oasis open org committees download php 10090 wss swa profile 1 0 draft 14 pdf This sample application was used as Sun s entry in a virtual interoperability demonstration sponsored by OASIS This sample implements a set of interop scenarios required by the event The scenarios addressed in this sample are described in The SwA Interop Scenarios Read more about the SwA interop scenarios at http lists oasis open org archives wss 200410 pdf00003 pdf The application prints out both the client and server request and response SOAP messages The output from the server may be viewed in the appropriate con tainer s log file The output from the client is sent to stdout or whichever stream is used by the configured log handler Messages are logged at the INFO level In this example server side code is found in the swainterop server src swainterop directory Client side code is found in the swainterop client src swainterop directory The asant or ant targets build objects under the build server and build client directories The SwA Interop Scenarios All four SwA interop scenarios use the same simple application The Requester sends a Ping element with a value of a str
69. SymmetricKey type SymmetricKey_T gt lt xs choice gt lt xs element name CanonicalizationMethod type CanonicalizationMethod_T minOccurs 0 maxOccurs 1 gt lt xs element name SignatureMethod type SignatureMethod_T minOccurs 0 maxOccurs 1 gt lt xs choice minOccurs 0 maxOccurs unbounded gt lt xs element name Target type Target_T minOccurs 0 maxOccurs unbounded gt lt xs element name SignatureTarget type SignatureTarget_T minOccurs 0 maxOccurs unbounded gt lt xs choice gt lt xs sequence gt lt xs attribute name id type id_T use optional gt lt xs attribute name requireTimestamp type xs boolean use optional default true gt lt xs complexType gt lt xs complexType name RequireEncryption_T gt lt xs sequence gt lt xs choice minOccurs 0 maxOccurs 1 gt lt xs element name X509Token type X509Token_T gt lt xs element name SAMLAssertion type SAMLAssertion_T gt lt xs element name SymmetricKey type SymmetricKey_T gt lt xs choice gt lt xs element name KeyEncryptionMethod type KeyEncryptionMethod_T minOccurs 0 maxOccurs 1 gt lt xs element name DataEncryptionMethod type DataEncryptionMethod_T minOccurs 0 maxOccurs 1 gt lt xs choice minOccurs 0 maxOccurs unbounded gt lt xs element name Target type Target_T gt lt xs element name EncryptionTarget FORMAL SCHEMA DEFINITION 111 type EncryptionTarget_T g
70. Synopsis 1s pattern URN Desc nption The 1s command lists the objects in the current RegistryPackage or when a pattern or URN is provided list the objects in the current RegistryPackage whose names in the current locale or unique identifiers match pattern or URN Operands pattern A pattern comprising literal characters and the special characters asterisk representing zero or more characters and question mark repre senting one and only one character You can specify more than one pattern URN A URN starting with urn for example urn uuid 4a6741e7 4bel 4cfb 960a e5520356c4fd You can specify more than one URN Examples The following command lists all the objects in the current RegistryPackage admin gt 1s The following command lists all the objects whose name matches the pattern urn bird poultry chicken or whose ID is urn bird poultry chicken admin gt ls urn bird poultry chicken 94 ADMINISTERING THE SERVICE REGISTRY The following command lists all the objects whose name matches the pattern bird It would also list the objects whose ID is bird if bird were a valid ID admin gt 1s bird The following command lists all the objects whose name matches the pattern bird or whose name matches the pattern urn bird poultry chicken or whose ID is urn bird poultry chicken admin gt ls bird urn bird poultry chicken pwd Displays the path to the current RegistryPackag
71. This method takes two arguments the target object and the concept that identifies the relationship 3 Use the RegistryObject addAssociation method to add the association to the source object CREATING RELATIONSHIPS BETWEEN OBJECTS ASSOCIATIONS 59 For example suppose you have two objects obj1 and obj2 and you want to establish a RelatedTo relationship between them In this relationship which object is the source and which is the target is arbitrary First locate the concept named RelatedTo Find RelatedTo concept for Association Collection namePatterns new ArrayListQ namePatterns addC RelatedTo BulkResponse br bqm findObjects Concept null namePatterns null null null null Collection concepts br getCollection Iterate through the concepts there should only be one to find the right one Concept relConcept Concept concIter next Create the association specifying obj2 as the target Association relAssoc blcm createAssociation obj2 relConcept Add the association to the source object obj1 objl addAssociation relAssoc Finally save the association Collection associations new ArrayListQ associations add relAssocl BulkResponse response blcm saveObjects associations Associations can be of two types intramural and extramural You create an intramural association when both the source and target object are owned by you You create an extramural association when at least
72. 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 created 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 TransformParame
73. a build xml file that allows you to compile and run each example using the Ant tool Each build xml file has a compi le target and one or more targets that run the example or examples Some of the run targets take command line arguments Before you run the examples you must edit two files in the directory lt INSTALL gt registry samples common The file build properties is used by the Ant targets that run the programs The file JAXRExamples properties is a resource bundle that is used by the programs themselves In addition a targets xm file in the lt INSTALL gt registry samples common directory defines the classpath for compiling and running the examples It also contains a clean target that deletes the build directory created when each exam ple is compiled Because Tomcat and the Sun Java System Application Server Platform Edition 8 1 have different file structures there are two versions of the build proper ties and targets xml files with the suffix tomcat for Tomcat and the suffix as for the Application Server Edit the file build properties as as follows 1 Set the property container home to the location of Sun Java System Application Server Platform Edition 8 1 2 Set the property registry home to the directory where you installed the Java WSDP 3 Set the properties proxyHost and proxyPort to specify your own proxy settings The proxy host is the system on your network through which you access the Internet You usuall
74. a connection a client first creates a set of properties that specify the URL or URLs of the registry or registries being accessed The following code provides the URLs of the query service and publishing service for the Registry if the Registry is deployed on the local system There should be no line break in the strings Properties props new Properties props setProperty javax xml registry queryManagerURL http localhost 8080 omar registry soap props setProperty javax xml registry 1lifeCycleManagerURL http localhost 8080 omar registry soap The client then obtains the connection factory as described in Creating a Con nection Factory page 8 sets its properties and creates the connection The fol lowing code fragment performs these tasks ConnectionFactory factory JAXRUti lity getConnectionFactoryQ factory setProperties props Connection connection factory createConnection The makeConnection method in the sample programs shows the steps used to create a JAXR connection OBTAINING AND USING A REGISTRYSERVICE OBJECT Table 8 1 lists and describes the two properties you can set on a connection These properties are defined in the JAXR specification Table 8 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 1ifeCycle
75. and Processing recommendation which can be viewed at http www w3 org TR xmldsig core sec Transforms The following types of transform algorithms can be used canonicalization Base64 xpath filtering envelope signature transform and XSLT transform The XWS Security APIs Sample Application provides some examples of configuration files that use this element SEMANTICS OF SECURITY CONFIGURATION FILE ELEMENTS Table 4 26 provides a description of its attributes Table 4 27 provides a description of its sub elements Table 4 26 Attributes of Transform Attributes of Transform Description The algorithm to be used for signing Required Table 4 27 Sub elements of Transform Sub elements of Transform Description E rege the parameters to be supplied to the transform algo AlgonthmParameter Algorithms are identified by URIs that appear as an attribute to the element that identifies the algorithms role DigestMethod Transform SignatureMethod or Canonical izationMethod All algorithms used herein take parameters but in many cases the parameters are implicit Explicit additional parameters to an algorithm appear as content elements within the algorithm role element Such parameter elements have a descriptive element name which is frequently algorithm specific and MUST be in the XML Signature namespace or an algorithm specific namespace The XWS Security APIs Sample Application provides some examples of configuration files t
76. 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 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 proper
77. 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 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 271 KedJuTob5gtvYx9qM3k3gm7kbLBwVbEQR126S2tmXjqNND7MRGtoew lt SignatureValue g
78. as when you add a new user using the Web Console or the JAXR API Specify the information about the user either on the command line itself or by using the load option to specify a Java properties file with the information The information options and the 1oad option are evaluated in the order they appear on the command line For example you can specify some properties on the com mand line load others from a properties file and then override information in the properties file with later command line options Specify at least one postal address telephone number and email address for the new user You can specify up to three of each type If you need more you can add them later using the Web Console or JAXR When you specify a postal address telephone number or email address you must provide a value for its type for example emai lType OfficeEmai1 You can use shorthand options such as fn on the command line for some of the common information that is required for every user but you must use the longer form when providing the information in a properties file For example you can specify the user s first email address on the command line using either emaill address emailAddress or email but when you specify it in a properties file you must use emaill address Because there is only one option for the user s second email address you must use email2 address on the command line and emai12 address in a properties file I
79. can be viewed at http xml apache org security Java security includes the Java Cryptography Extension JCE and the Java Cryptography Architecture JCA JCE and JCA form the foundation for public key technologies in the Java platform The JCA API specification can be viewed at http java sun com j2se 1 5 0 docs guide security CryptoSpec html The JCE documenta tion can be viewed at http java sun com products jce reference docs index html Interoperability with Other Web Services One of the goals of XML and Web Services Security technology is to enable applications to be able to securely interoperate with clients and web service end points deployed on other Java application servers and other web services plat forms To accomplish this interoperability an open industry organization Web Ser vices Interoperability WS I Organization was chartered to promote Web ser vices interoperability across platforms operating systems and programming languages WS I is developing an interoperability profile WS I Basic Security Profile 1 0 BSP that deals with transport security SOAP messaging security and other Basic Profile oriented Web services security considerations XWS Security EA 2 0 provides partial support for BSP complete support is planned for the FCS release of 2 0 What is Basic Security Profile BSP In terms of XWS Security Basic Security Profile BSP support means that BSP compliant requests will be generated and
80. 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 84 UsING JAXB 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 lt xs choice gt lt xs group gt lt xs schema gt Customizing a choice Model Group The lt JWSDP_HOME gt jaxb samples bind choice binding xjb binding decla rations file demonstrates one way to override the default derived names for choice model groups in example xsd by means of a lt jxb globalBindings gt declaration 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
81. create an Organization and add a Ser vice to it an Association of type OffersService is automatically created from the Organization to the Service If no valid reference exists for the source and target objects you cannot create a reference You use the Relate button in the Registry Objects area to relate two objects This button becomes active when you select two objects in the search results table If the two objects are not both visible in the search results table select the Pin checkbox to hold one object in the search results table while you find the object to which you want to relate it Creating References To create a Reference follow these steps 1 In the Registry Objects area select two objects and click Relate 2 In the Create Relationship area select the source object if it is not already selected The other object becomes the target object 3 If a valid reference exists for the source and target objects the Reference option is selected by default and the valid reference attribute appears If no valid reference exists for the source and target objects the Reference radio button is grayed out 4 Click Save to save the Reference Creating Associations To create an Association follow these steps 1 In the Registry Objects area select two objects and click Relate 2 In the Create Relationship area select the source object if it is not already selected CREATING RELATIONSHIPS BETWEEN OBJECTS 305
82. dation SignatureMethod 158 INTRODUCTION TO XML AND WEB SERVICES SECURITY Table 4 21 Sub elements of RequireSignature Continued Sub elements of RequireSignature Description Specifies the target message part which was expected to be Target signed Target has been deprecated and is only provided for backward compatibility Specifies the target message part which was expected to be SignatureTarget spud RequireEnc ryption The lt RequireEncryption gt element is used when encryption is required for all incoming messages If encryption is not present an exception is thrown In this release the only sub elements of RequireEncryption that are verified during validation of encrypted data in incoming messages are Target and Encryption Target Table 4 22 provides a description of its attributes Table 4 23 provides a description of its sub elements Table 4 22 Attributes of RequireEncryption Attributes of RequireEncryption Description The id to be set on the message to be sent Table 4 23 Sub elements of RequireEncryption Sub elements of RequireEncryption Description Indicates the certificate to be used for encryption If this ele ment is not present attempt is made to get the default certifi X509Token cate from the security environment handler Only one of the X509Token SAMLAssertion and SymmetricKey elements may be present at a time SEMANTICS OF SECURITY CONFIGURATION FILE ELEMENTS 159 T
83. down list is RegistryObject which searches all objects in the Registry To narrow the search change the object type Follow these steps 1 Choose an object type from the Object Type drop down list 287 288 USING THE SERVICE REGISTRY WEB CONSOLE 2 Click the Search button The search returns all objects of the specified type You can narrow the search by specifying a name description or classification Searching by Name and Description To search by the name or description of an object follow these steps 1 From the Select Predefined Query drop down list select either Basic Query or Basic Query Case Sensitive 2 Type a string in the Name or Description field 3 Click Search By default the search looks for a name or description that matches the entire string you typed You can use wildcards to find a range of objects The wildcard characters are percent and underscore _ The wildcard matches multiple characters e Type off to return words that contain the string off such as Coffee e Type nor to return words that start with Nor or nor such as North and northern e Type ica to return all words that end with ica such as America The underscore wildcard matches a single character For example the search string _us_ would match objects named Aus1 and Bus3 Searching by Classification Classification objects classify or categorize objects in the registry using unique concepts that define v
84. e Add lt JWSDP_HOME gt jwsdp shared bin to the front of your path so the Java WSDP 1 6 scripts that are shared by multiple components override other installations e Add lt JWSDP_HOME gt apache ant bin to the front of your path so that the Java WSDP 1 6 Ant script overrides other installations Further Information This tutorial includes the basic information that you need to deploy applications on and administer the Application Server For reference information on the tools distributed with the Application Server see the man pages at http docs sun com db doc 819 0082 See the Sun Java System Application Server Platform Edition 8 1 2005Q1 Developer s Guide at http docs sun com db doc 819 0079 for informa tion about developer features of the Application Server See the Sun Java System Application Server Platform Edition 8 1 2005Q1 Administration Guide at http docs sun com db doc 819 0076 for informa tion about administering the Application Server For information about the PointBase database included with the Application Server see the PointBase Web site at ww pointbase com 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 xvi ABOUT THIS TUTORIAL Typographical Conventions Table 2 lists the typographical conventions used in this t
85. 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 64 USING JAXB 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 customizations is lt property name propertyName collectionType propertyCollectionType fixedAttributeAsConstantProperty true false 1 o generateIsSetMethod true false 1 o enableFailFastCheck true false 1 OQ J lt baseType gt lt baseType gt lt javadoc gt lt javadoc gt lt property gt lt baseType gt lt javaType gt lt javaType gt lt baseType gt name defines the customization value propertyName it must be a legal Java identifier collectionType defines the customization value propertyCol lection 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 implemen
86. example sign client xm1 looks like this lt xwss JAXRPCSecurity xmins xwss http java sun com xml ns xwss config gt lt xwss Service gt lt xwss SecurityConfiguration dumpMessages true gt lt USING THE CALLBACKHANDLER TO ENABLE DYNAMIC RESPONSE 261 Note that in the lt Sign gt operation a Timestamp is exported in the security header and signed by default gt lt xwss Sign gt lt xwss X509Token certificateAlias xws security client gt lt xwss Sign gt lt xwss RequireEncryption gt lt xwss SecurityConfiguration gt lt xwss Service gt lt xwss SecurityEnvironmentHandler gt sample SecurityEnvironmentHandler lt xwss SecurityEnvi ronmentHand1er gt lt xwss JAXRPCSecurity gt The server security configuration file for this example encrypt server xm looks like this lt xwss JAXRPCSecurity xmIns xwss http java sun com xml ns xwss config gt lt xwss Service gt lt xwss SecurityConfiguration dumpMessages true gt lt xwss RequireSignature gt lt xwss Encrypt gt lt xwss SecurityConfiguration gt lt xwss Service gt lt xwss SecurityEnvironmentHandler gt sample SecurityEnvironmentHandler lt xwss SecurityEnvi ronmentHand1er gt lt xwss JAXRPCSecurity gt Using the CallbackHandler to Enable Dynamic Response In this sample application the security configuration files sign the request and encrypt the response however the work of using the
87. gt lt xwss Service gt lt xwss SecurityConfiguration dumpMessages true gt lt Default Digested password will be sent gt lt xwss UsernameToken name Ron password noR gt lt xwss SecurityConfiguration gt lt xwss Service gt lt xwss SecurityEnvironmentHandler gt com sun xml wss sample SecurityEnvironmentHandler lt xwss SecurityEnvi ronmentHandler gt lt xwss JAXRPCSecurity gt The simple sample application includes a number of example security configu ration files The sample configuration files are located in the directory lt JWSDP_HOME gt xws security samples simple config Further discussion of the example security configurations can be found in Simple Sample Security Con figuration Files Other sample configuration files that are provided in this release include Simple Sample Security Configuration Files JAAS Sample Security Configuration Files SwA Sample Configuration Files SAML Interop Sample Configuration Files Security Configuration Files for Enabling Dynamic Policy Security Configuration Files for Enabling Dynamic Response XWS Sec unty Configuration File Schema When creating a security configuration file there is a hierarchy within which the XML elements must be listed This section contains an abstract sketch of the schema for the data for security configuration files The formal schema definition can be viewed at A XWS Security Formal Schema Definition 140 INTRODUC
88. identifier 25 retrieving version information 34 saving 294 56 searching by classification 288 searching by name and de scription 288 searching by object type 287 using create methods 44 viewing search results 291 Registry Objects area 291 registry providers definition 2 RegistryObject interface 3 RegistryPackage interface 12 creating objects 64 RegistryPackage location changing 86 RegistryPackage objects creating 72 displaying path to 94 listing contents 92 removing member objects 95 RegistryService interface 3 9 removing objects from Registry Package 95 removing registry objects 303 repositories definition 2 storing items in 60 request signing and encrypting 215 251 253 request inner classes methods 180 requests authenticating 219 227 240 decrypting 214 216 dumping 213 encrypting 214 encrypting and signing 216 signing 214 signing and encrypting 214 INDEX 131 signing ticket element and message body 223 username token 219 227 240 username token and encrypt 220 221 RequireEncryption element 136 RequireSignature element 136 responses dumping 213 encrypting 214 signing 214 signing and encrypting 214 ResponseStatusType classifica tion scheme 19 restoring Registry database 101 rm command 95 root command line option 73 RSA encryption 207 S sample applications XWS Security 174 interop 174 simple 130 131 174 running 211 225 229 247 254 258 262 running against a re mote server 226
89. 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 instances of interfaces JAXBinterface method that enables you to create USING JAXB These classes and their specific bindings to the source XML schema for the basic examples are described below Table 2 4 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 purchaseOrder 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 bil1lTo 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 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 Zzip type xsd
90. interface 55 addServices method Organiza tion interface 55 addSpeci fi cationLink method ServiceBinding interface 63 AdhocQueryManagerImp1 class 38 Admin Tool command line options 71 introduction 69 starting 70 stopping 94 alias command line option 71 Apache 132 approveObjects method LifeCy cleManagerImp 1 class 66 approving registry objects 302 65 example 66 Association interface 11 creating objects 57 associations adding to registry 76 creating 303 AssociationType scheme 18 57 concepts 58 audit trails generating events 65 retrieving 33 viewing 291 classification 121 122 INDEX AuditableEvent interface 11 retrieving objects 33 B backing up Registry database 101 Basic Security Profile BSP 133 batch mode 70 BSP 133 build properties file JAXR examples 5 BusinessLifeCycleManager inter face 4 9 41 BusinessQueryManager interface 4 9 C Callback 180 Callback classes summary 180 CallbackHandler interface 177 case sensitivity 75 cd command 86 certificates obtaining 7 child organizations adding to organizations 300 chown command 87 Classification interface 11 adding objects 47 retrieving objects 26 using to find objects 17 classification schemes 288 adding child concepts 302 creating with JAXR 45 ebXML specification 17 classifications adding to registry objects 295 searching by 288 ClassificationScheme 12 clients JAXR 3 examples 5 setting up 7 command command line option 71
91. inventors of the tech nology If you are running the Application Server on version 1 5 of the Java SDK the JCE provider is already configured properly If you are running the Application Server on version 1 4 x of the Java SDK follow these steps to add a JCE pro vider statically as part of your JDK environment 1 Download and install a JCE provider JAR Java ARchive file The follow ing URL provides a list of JCE providers that support RSA encryption http java sun com products jce jce14_providers html 2 Copy the JCE provider JAR file to lt JAVA_HOME gt jre lib ext Stop the Application Server or other container If the Application Server is not stopped and restarted later in this process the JCE provider will not be recognized by the Application Server Edit the lt JAVA_HOME gt jre lib security java security properties file in any text editor Add the JCE provider you ve just downloaded to this file The java security file contains detailed instructions for adding this provider Basically you need to add a line of the following format in a location with similar properties security provider lt n gt lt provider class name gt In this example lt n gt is the order of preference to be used by the Applica tion Server when evaluating security providers Set lt n gt to 2 for the JCE provider you ve just added For example if you ve downloaded ABC JCE provider and the Java class name of the AB
92. is disabled by default All objects have a version of 1 1 even after modification For details on how to turn versioning on see the Release Notes To retrieve the version of an object use the implementation specific getVer sionInfo method for a registry object which returns a VersionInfoType object The method has the following signature public VersionInfoType getVersionInfo Q throws JAXRException For example to retrieve the version number for the organization org cast org to a RegistryObjectImp1 when you call the method Then call the VersionInfo Type getVersionName method which returns a String import org oasis ebxml registry bindings rim VersionInfoType VersionInfoType vinfo CRegistryObjectImp1 org getVersioninfoQ if vInfo null System out printInC Org version vinfo getVersionName Some of the examples use code similar to this See for example JAXRQuery ByName java in Finding Objects by Name Example page 16 Using Declarative Quenes Instead of the BusinessQueryManager interface you can use the Declarative QueryManager interface to create and execute queries to the Registry If you are familiar with SQL you may prefer to use declarative queries The Declara tiveQueryManager interface depends on another interface Query The DeclarativeQueryManager interface has two methods createQuery and executeQuery The createQuery method takes two arguments a query type and a string contai
93. like SAX and DOM allow schema validation to be dis abled and there are cases in which you may want to disable schema validation to improve processing speed and or to process documents containing invalid or incomplete content JAXB supports these processing scenarios by means of the exception handling you choose implement in your JAXB enabled application In general if a JAXB implementation cannot unambiguously complete unmarshal ling or marshalling it will terminate processing with an exception Note The Validator class is responsible for managing On Demand Validation see below The Unmarshal ler class is responsible for managing Unmarshal Time Validation during the unmarshal operations Although there is no formal method of enabling validation during the marshal operations the Marshaller may detect errors which will be reported to the ValidationEventHandler registered on it A JAXB client can perform two types of validation e Unmarshal Time validation enables a client application to receive informa tion about validation errors and warnings detected while unmarshalling XML data into a Java content tree and is completely orthogonal to the other types of validation To enable or disable it use the Unmar shaller setValidating method All JAXB Providers are required to support this operation e On Demand validation enables a client application to receive information about validation errors and warnings detected in the Java conten
94. lt xwss Encrypt gt lt xwss RequireSignature gt lt xwss SecurityConfiguration gt lt xwss Operation name http xmlsoap org Ping Ping gt lt xwss Operation name http xmlsoap org Ping PingQ gt lt xwss Port gt lt xwss Service gt lt xwss SecurityEnvi ronmentHandler gt sample SecurityEnvironmentHandler lt xwss SecurityEnvi ronmentHand1er gt lt xwss JAXRPCSecurity gt RUNNING THE SIMPLE SAMPLE APPLICATION In this example the following has been configured for the Ping operation under port instance Ping e Inserts a UsernameToken into the request e Signs the ticket and text child elements of the request body e Encrypts the contents of the request body The following has been configured for the Ping operation under port instance Ping e Encrypt the content of the body of the message When the xwss Encrypt element is specified with no child elements of type xwss Target it implies that the default Target which is SOAP ENV Body has to be encrypted The same rule applies to xwss Sign elements with no child ele ments of type xwss Target The configuration file in this example also configures the following security for all the WSDL operations under port instance Ping e Encrypts the request body e Expects a signed response from the server Username Running the Smple Sample Application To run the simple sample application follow these steps 1 Complete the tasks defined in the foll
95. make access control decisions The SAML Sample Application provides some examples of using this element Table 4 17 provides a description of attributes of the lt SAMLAssertion gt element Table 4 17 Attributes of SAMLAssertion Attributes of SAMLAssertion Description id Identifier for an assertion Defines the ID that may be used to acquire the identified asser authoritylId fi 4 tion at a SAML assertion authority or responder Element content of the string identifier for the keyIdenti fier The ID for a token reference for the key identifier that refer keyIdenti fier ences a local SAML assertion A parameter used to identify the security reference When the encodingType keyIdenti fier is used this attribute is prohibited Prohib ited Indicates whether the token reference identifies a token by keyReferenceType URI Identifier or by an embedded reference Embed ded The default value is Identifier SEMANTICS OF SECURITY CONFIGURATION FILE ELEMENTS 155 Table 4 17 Attributes of SAMLAssertion Continued Attributes of SAMLAssertion Description Indicates the type of SAML assertion to use The choices are Holder of Key HOK and Sender Vouches SV The SV con firmed assertion may not be contained in the message The Security Token Reference STR identified in strID becomes a remote reference to the SV confirmed assertion The HOK assertion contained in the message identifies the attesting
96. 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 SCHEMA DERIVED JAXB CLASSES 41 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 the following methods getItems 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 e getShipToQ e setShipTo primer po USAddress value 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 getShiploQ void setShipTo primer po USAddress value 42 USING JAXB USAddress java In USA
97. of UsernameToken Attributes of UsernameToken Description The name of the user If not specified security environment handler must provide it at runtime The password of the user If not specified attempt would be password made to obtain it from the security environment handler at runtime SEMANTICS OF SECURITY CONFIGURATION FILE ELEMENTS 151 Table 4 13 Attributes of UsernameToken Continued Attributes of UsernameToken Description Indicates whether to send password in digest form or not digestPassword 9 Default value is true Indicates whether to send a nonce inside the username token useNonce or not Sending a nonce helps in preventing replay attacks Default value is true The id to be set on the username token in the message to be sent This is also useful in referring to the token from other places in the security configuration file Sign The lt Sign gt element is used to indicate that a sign operation needs to be per formed on the outgoing messages Table 4 14 provides a description of its attributes Table 4 15 provides a description of its sub elements Table 4 14 Attributes of Sign The id to be set on the signature of the message to be sent This is also useful in referring to the signature from other places in the security configuration file Indicates whether to also sign a timestamp as part of this sig nature or not This is a mechanism useful in preventing replay attacks The d
98. of XML Schema JAXB supports the grouping of generated classes and interfaces in Java pack ages A package comprises e A name which is either derived directly from the XML namespace URI or specified by a binding customization of the XML namespace URI e A set of Java content interfaces representing the content models declared within the schema e A Set of Java element interfaces representing element declarations occur ring within the schema 17 18 BINDING XML SCHEMA TO JAVA CLASSES WITH JAXB e An ObjectFactory class containing e An instance factory method for each Java content interface and Java ele ment interface within the package for example given a Java content interface named Foo the derived factory method would be public Foo createFoo throws JAXBException e Dynamic instance factory allocator creates an instance of the specified Java content interface for example public Object newInstance Class javaContentInterface throws JAXBException e getProperty and setProperty APIs that allow the manipulation of provider specified properties e Set of typesafe enum classes e Package javadoc 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 The topics in this section are as follows e Simple Type Definitions e Default Data Type Bindings e Default Bindi
99. only created if the document being processed contains a DTD ITERATOR API Sample Event Mapping 95 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 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 3 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 lement qname Book attributes null namespaces null StartE ement 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 96 STREAMING API FOR XML Table 3 3 Sample Iterator API Event Mapping Continued Element Attr
100. optional callbacks and the details of the Callback classes When XWS Security is used in a stand alone SAAJ environment the developer can choose to implement the com sun xml wss SecurityEnvironment inter face instead of a callback handler that handles XWS Security callbacks In this situation an instance of the SecurityEnvironment implementation can be set into the ProcessingContext instance For an example application that demon strates this refer to the XWS Security APIs Sample Application For more details on the SecurityEnvironment interface refer to the javadocs at lt JWSDP_HOME gt xws security docs api com sun xml wss SecurityEnvironment htm1 Another type of security mechanism that can be specified in the security config uration file is user name authentication In the case of user name authentication the user name and password of a client need to be authenticated against the user password database of the server The xwss element specifies that the security mechanism to use is UsernameToken On the server side refer to the documenta tion for your server regarding how to set up a user password database for the server or read Setting Up To Use XWS Security With the Sample Applications for a sum XWS SECURITY CONFIGURATION FILE SCHEMA 139 mary A client side security configuration file that specifies UsernameToken authentication would look like this lt xwss JAXRPCSecurity xmIns xwss http java sun com xml ns xwss config
101. process of converting XML content to a canonical form to take 272 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 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 signat
102. purpose of the Modify Marshal example is to demonstrate how to modify a Java content tree 1 The lt JWSDP_HOME gt jaxb samp1les modi fy 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 import java math BigDecimal import javax xml bind JAXBContext import javax xml bind JAXBException import javax xml bind Marshaller import javax xml bind Unmarshaller ke 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 and po xm1 is unmarshalled USING JAXB 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 setPrope
103. requester certificate to encrypt the response back to the requester is done in the SecurityEnvironmen tHandler The full source code for the SecurityEnvironmentHandler is 262 UNDERSTANDING AND RUNNING THE XWS SECURITY SAMPLE APPLICATIONS located in the directory dynamic response src sample This snippet from that file demonstrates how to use a CallbackHandler to generate the response dynamically if cb getRequest instanceof EncryptionKeyCallback Aliasx509CertificateRequest EncryptionKeyCal lback Aliasx509CertificateRequest request CEncryptionKeyCal lback AliasX509Certi ficateRequest cb getRequest String alias request getAliasQ if CCalias null equals alias Subject currentSubject SubjectAccessor getRequesterSubjectQ Set publicCredentials currentSubject getPublicCredentialsQ for Iterator it publicCredentials iterator it hasNextQ Object cred it nextQ if cred instanceof java security cert X509Certificate java security cert X509Certificate cert java security cert X509 Certificate cred request setxX509Certificate cert Running the Dynamic Response Sample Application To run the dynamic response sample application follow these steps 1 Complete the tasks defined in the following sections of this addendum Setting System Properties Configuring a JCE Provider Setting Build Properties 2 Start the selected container and make sure the server is running To start th
104. scenarios addressed in this interop are described in SAML Interop Scenarios Read more about the SAML interop scenarios at the fol lowing URL _ http www oasis open org apps org workgroup wss download php 701 1 wss saml interop1 draft 11 doc The application prints out both the client and server request and response SOAP messages The output from the server may be viewed in the appropriate con tainer s log file The output from the client is sent to stdout or whichever stream is used by the configured log handler Messages are logged at the INFO level In this example server side code is found in the swainterop server src swainterop directory Client side code is found in the swainterop client src swainterop directory The asant or ant targets build objects under the build server and build client directories SAML Interop Scenanos All four SAML interop scenarios invoke the same simple application The Requester sends a Ping element with a value of a string The value of the string should be the name of the organization that has developed the software and the number of the scenario e g Sun Microsystems Scenario 1 The Responder returns a PingResponse element with a value of the same string These scenarios use the Request Response Message Exchange Pattern MEP with no intermedi aries All scenarios use SAML v1 1 Assertions To validate and process an assertion the receiver needs to establish the relation s
105. such information in various ways such as looking up a keystore with an alias using the default key pairs available with the container looking up a truststore with an alias etc Similarly if an application wants to send a username password in a UsernameToken it can choose to obtain the user name password pair in various ways such as reading from a file prompting the user on the console using a popup window etc The authentication of the user name password on the receiving application can similarly be done by plugging into existing authentication infrastructure using a proprietary username pass word database etc To support these possibilities XWS Security defines a set of CallBack classes and requires the application to define a Cal1BackHandler to handle these call backs The xwss SecurityEnvironmentHandler element is a compulsory child element that needs to be specified The value of this element is the class name of a Java class that implements the javax security auth callback Cal1lback Handler interface and handles the set of callbacks defined by XWS Security There are a set of callbacks that are mandatory and every CallbackHandler needs to implement them A few callbacks are optional and can be used to sup ply some fine grained property information to the XWS Security run time When using the XWS Security APIs for securing both JAX RPC applications and stand alone applications that make use of SAAJ APIs only for their SOAP 178
106. tainer s log file The output from the client is sent to stdout or whichever stream is used by the configured log handler Messages are logged at the INFO level In this example server side code is found in the jaas sample server src jaas sample directory Client side code is found in the jaas sample cli ent src jaas sample directory The asant or ant targets build objects under the build server and build client directories J AAS Sample Security Configuration Files The security configuration pair user pass authenticate client xml and user pass authenticate server xm enable the following tasks e Client adds a username password token and sends a request e Server authenticates the username and password against a username pass word database e Server sends response The username password database must be set up before this security configura tion pair will run properly Refer to Setting Up For the JAAS Sample for instructions on setting up this database The user pass authenticate client xm file looks like this lt xwss JAXRPCSecurity xmIns xwss http java sun com xml ns xwss config gt lt xwss Service gt lt xwss SecurityConfiguration dumpMessages true gt 227 228 UNDERSTANDING AND RUNNING THE XWS SECURITY SAMPLE APPLICATIONS lt xwss UsernameToken digestPassword false gt lt xwss SecurityConfiguration gt lt xwss Service gt lt xwss SecurityEnvironmentHandler gt sample ClientSe
107. tasks defined in the following sections of this addendum e Setting System Properties Configuring a JCE Provider Setting Build Properties 2 Start the selected container and make sure the server is running To start the Application Server a From a Unix machine enter the following command from a terminal window asadmin start domain domainl 248 UNDERSTANDING AND RUNNING THE XWS SECURITY SAMPLE APPLICATIONS b From a Windows machine choose Start gt Programs Sun Microsystems J2EE 1 4 Start Default Server 3 Make sure that you have modified the swainterop build properties file for this sample as described in Setting Build Properties 4 Build and prompt run the application from a terminal window or command e On the Application Server the command to build and run the applica tion is asant run samp1e lt number gt e On the other containers the command to build and run the application is ant run samp1e lt number gt Where the lt number gt variable is the number of the interop scenario you want to run Note To run the sample against a remote server containing the deployed endpoint use the run remote sample target in place of the run samp e target In this situa tion make sure that the endpoint host endpoint port http proxyHost http proxyPort and service url properties are set correctly in the build prop erties file as discussed in Setting Build Properties before running the sample
108. that are of a particular object type To retrieve all the objects you have published use the no argument version of the QueryManager getRegistryObjects method The name of this FINDING OBJECTS YOU PUBLISHED method is misleading because it returns only objects you have published not all registry objects For example if bqm is your BusinessQueryManager instance use the following line of code BulkResponse response bqm getRegistryObjectsQ To retrieve all the objects of a particular type that you published use QueryManager getRegistryObjects with a String argument BulkResponse response bqm getRegistryObjects Service This method is case sensitive so the object type must be capitalized The sample programs JAXRGetMyObjects and JAXRGetMyObjectsByType show how to use these methods Finding Objects You Published Examples For examples of finding objects by classification see the two examples in lt INSTALL gt registry samples get objects src JAXRGetMyObjects java and JAXRGetMyObjectsByType java The first example JAXRGetMyOb jects java retrieves all objects you have published The second example JAXRGetMyObjectsByType java retrieves all the objects you have published of a specified type To run the examples follow these steps 1 Go to the directory lt INSTALL gt registry samples get objects 2 Type the following command to retrieve all objects you published ant get obj 3 Type the following command to r
109. 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 redeclared 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 st
110. the Web tier section of the Security chapter After you have become familiar with some of the technology areas you are ready to tackle a case study which ties together several of the technologies dis cussed in the tutorial The Coffee Break Application Chapter 35 describes an application that uses the Web application and Web services APIs Finally the following appendixes contain auxiliary information helpful to the Web Services application developer Java encoding schemes Appendix A XML Standards Appendix B HTTP overview Appendix C About the Examples This section tells you everything you need to know to install build and run the examples xiii xiv ABOUT THIS TUTORIAL Required Software Java WSDP 1 6 Bundle The example source for the technologies in this tutorial is contained in the Java WSDP 1 6 bundle If you are viewing this online you need to download the Java WSDP 1 6 bundle from http java sun com webservices download webservicespack htm After you have installed the Java WSDP 1 6 bundle the example source code is in the subdirectories of the lt JWSDP_HOME gt lt technology gt samples directory For example the examples for JAXB are included in the Java WSDP in the sub directories of the lt JWSDP_HOME gt jaxb samples directory Application Server Sun Java System Application Server Platform Edition 8 1 2005Q2 UR2 is the build and runtime environment for the tutorial examples To build
111. the application runs successfully you will see a message similar to the follow ing echo Running the client program java Sending Message Start java Sending Message End java Received Message Start java Received Message End You can view similar messages in the server logs lt SJSAS_HOME gt domains lt domain name gt logs server log lt TOMCAT_HOME gt logs launcher server log lt SJISWS_HOME gt lt Virtual Server Dir gt logs errors J AAS Sample Application The Java Authentication and Authorization Service JAAS is a set of APIs that enable services to authenticate and enforce access controls upon users It imple ments a Java technology version of the standard Pluggable Authentication Mod ule PAM framework and supports user based authorization JAAS SAMPLE SECURITY CONFIGURATION FILES The lt JWSDP_HOME gt xws security samples jaas sample application demon strates the following functionality e Obtaining a user name and password at run time and sending it in a Web Services Security WSS UsernameToken to the server e Using JAAS authentication to authenticate the user name and password in the server application e Accessing the authenticated sender s subject from within the endpoint implementation methods The application prints out both the client and server request and response SOAP messages The output from the server may be viewed in the appropriate con
112. the samples are run using ASAnt tasks the user name and pass word for this example are set as a system property The build xml file for the jaas sample example includes the following line under the run sam ple target that uses a user name and password supplied in the lt JWSDP_HOME gt xws security etc userpasslist xml file lt sysproperty key username password value Ron noR gt The JAAS login module also makes use of the userpasslist xm file so make sure that this file exists and contains the user name and password specified in the build xm1 file 3 Add the following JAAS policy to the JAAS policy file of the Application Server This file can be found at lt SJSAS_HOME gt domains domain1 con fig login conf Add the following code near the end of the file Login Configuration for the Sample Application XWS_SECURITY_SERVER com sun xml wss sample UserPassLogin Module REQUIRED debug true 35 4 Add the following permissions to the server policy file of the Application Server This file can be found at lt SJSAS_HOME gt domains domain1 con fig server policy Add the following code near the end of the file 229 230 UNDERSTANDING AND RUNNING THE XWS SECURITY SAMPLE APPLICATIONS grant codeBase file com sun aas instanceRoot applica tions j2ee modules jaassample WEB INF permission javax security auth AuthPermission modi fyPrincipals permission javax security auth AuthPermission modi fyPr
113. to mean http www w3 org 2000 09 xmld Optional callback to register any prefix versus namespace uri mappings that the devel oper wants to make use of in the security configuration Prefix i ifyi sig Namespac e Targets 4 Prefix xenc to mean http e P i www w3 o0rg 2001 04 Mapping Refer to the API documenta i lence Callback erie are 5 Prefix wsse to mean http y p docs oasis open org sun xml wss impl cal1 wss 2004 01 oasis back Prefix z F 200401 wss wssecurity NamespaceMappingCallba ck htm1 for more details rikveck mnatious i 6 Prefix wsu to mean http docs oasis open org wss 2004 01 oasis 200401 wss wssecurity uti lity 1 0 xsd 7 Prefix wsu to mean http docs oasis open org wss 2004 01 oasis 200401 ws s wssecurity uti lity 1 0 xsd The use of XPath expressions is discouraged in XWS Security EA 2 0 because it impacts per formance Users are advised to make use of fragment URI s and QNames to identify targets of signature and encryption WRITING SECURITYENVIRONMENTHANDLERS Table 4 41 Summary of Callback classes and their Request types Continued Callback Certifi cate Valida tion Callback Description This callback is intended for X 509 certificate validation A validator that implements the CertificateValida tor interface should be set on the callback by the call back handler Currently this callback is invoked by the XWS Secu rity runtime whenever
114. unty Command Line Tools In this release the following command line tools are included These tools pro vide specialized utilities for keystore management or for specifying security con figuration files e pkcs12import e keyexport e wscompile For more information on keystore management read the Application Server Administration Guide topic Working with Certificates and SSL pkcsl2import The pkcs12import command allows Public Key Cryptography Standards ver sion 12 PKCS 12 files sometimes referred to as PFX files to be imported into a keystore typically a keystore of type Java KeyStore JKS When would you want to do this One example would be a situation where you want to obtain a new certificate from a certificate authority In this scenario one option is to follow this sequence of steps 1 Generate a key pair 2 Generate a certificate request 198 INTRODUCTION TO XML AND WEB SERVICES SECURITY 3 Send the request to the authority for its signature 4 Get the signed certificate and import it into this keystore Another option is to let the certificate authority generate a key pair The author ity would return a generated certificate signed by itself along with the corre sponding private key One way the certificate authority can return this information is to bundle the key and the certificate in a PKCS 12 formatted file generally pfx extension files The information in the PKCS 12 file would be encrypted us
115. useful primarily for searching UDDI registries The more general findObjects method and the Registry0b ject getter methods are more appropriate for the Service Registry To execute queries you do not need to log in to the Registry By default an unauthenticated user has the identity of the user named Registry Guest J AXR Information Model Interfaces Table 8 2 lists the main interfaces supported by the JAXR information model All these interfaces extend the RegistryObject interface Table 8 2 JAXR RegistryObject Subinterfaces Defines a relationship between two objects Getter finder meth ods RegistryObject getAssociations BusinessQue ryManager findAssociations BusinessQueryManager findCallerAssociations Association Provides a record of a change to an object A collection of Aud AuditableEvent itableEvent objects constitutes an object s audit trail Getter method RegistryObject getAuditTrail Classifies an object using a ClassificationScheme Getter method RegistryObject getClassifications Classification 11 12 DEVELOPING CLIENTS FOR THE SERVICE REGISTRY Table 8 2 JAXR RegistryObject Subinterfaces Continued Object Type ClassificationScheme Description Represents a taxonomy used to classify objects An internal Classi ficationScheme is one in which all taxonomy ele ments concepts are defined in the registry An external Clas sificationScheme is one in which the values are not defined
116. value USING THE EXPLORE MENU The Audit Trail tab does not produce a table with a Details link Instead it pro duces a table containing the event type the date and time of the event and the name of the User that caused it For every object the Unique Identifier is an active link Click this link to view the XML for the object in a web browser window All registry objects are stored in XML format If the object is an Externalldentifier the details panel has a Display Content link Click this link to view the object in a web browser window If the object is an ExtrinsicObject the details panel has a View Repository Item Content link Click this link to view the repository item in a web browser win dow Using the Explore Menu The Explore menu allows you to navigate through Registry and Repository con tent using the metaphor of a hierarchy of file folders The root folder named root contains all Registry content and is similar to the UNIX root directory To use the Explore menu follow these steps 1 Click the Explore link 2 Expand the folder named root It contains two subfolders userData where all user content is placed and ClassificationSchemes To explore the classification schemes follow these steps 1 Click the ClassificationSchemes folder not the node symbol All the ClassificationScheme objects appear in the Registry Objects area Follow the instructions in Viewing Search Results page 291 to vi
117. w3 org 2001 XMLSchema xmIns jxb http java sun com xml ns jaxb jxb version 1 0 gt Namespace Declarations As shown in JAXB Version Namespace and Schema Attributes page 76 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 EXTERNAL CUSTOMIZE EXAMPLE Schema Name and Schema Node The fourth line of the code in JAXB Version Namespace and Schema Attributes page 76 specifies the name of the schema to which 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 lt xS appinfo gt elements which are in turn embedded in lt xs annotation gt ele ments Embedding declarations in th
118. wss 2004 01 oasis 200401 wss wssecurity secext 1 0 xsd UsernameToken lt xwss Target gt 222 UNDERSTANDING AND RUNNING THE XWS SECURITY SAMPLE APPLICATIONS lt xwss Encrypt gt lt xwss SecurityConfiguration gt lt xwss Service gt lt xwss SecurityEnvi ronmentHandler gt sample SecurityEnvironmentHandler lt xwss SecurityEnvi ronmentHand1er gt lt xwss JAXRPCSecurity gt Hexibility in Positions of Timestamps and Tokens The security configuration pair flexiblec xml and flexibles xm1 demon strate the flexibility in the position of Timestamps and tokens allowed in the receiver side processing of a message The tokens that can be used include UsernameToken BinarySecurityToken SAMLAssertion and others The posi tion of lt RequireXxX gt elements for these tokens can vary in the receiver side configuration file regardless of the position of the tokens in the incoming mes sage This flexibility does not apply to the relative position of Signature and EncryptedData elements in the incoming message which have to follow the strict order in which the lt RequireSignature gt and lt RequireEncryption gt ele ments appear in the configuration file The flexiblec xm1 file looks like this lt xwss JAXRPCSecurity xmIns xwss http java sun com xml ns xwss config gt lt xwss Service gt lt xwss SecurityConfiguration dumpMessages true xmIns xwss http java sun com xml ns xwss config gt lt xwss Sign i
119. xs appinfo gt 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 JAXB binding dec larations file specifies the schema name and the root schema node lt jxb bindings schemaLocation po xsd node xs schema gt 57 58 USING JAXB 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 bindin
120. 0 i lt callbacks length i if Ccallbacks i instanceof SignatureVerificationKeyCallback SignatureVeri ficationKeyCal lback callbacks i if cb getRequest instanceof SignatureVerificationKeyCallback X509Subj ectKeyIdentifierBasedRequest subject keyid request SignatureVerificationKeyCallback X509Subj ectKeyIdentifierBasedRequest request SignatureVerificationKeyCallback X50 WRITING SECURITYENVIRONMENTHANDLERS 195 9SubjectKeyIdentifierBasedRequest cb getRequest locate and setx509Certificate on the request else if cb getRequest instanceof SignatureVeri ficationKeyCal lback X509I ssuerSerialBasedRequest issuer serial request SignatureVeri ficationKeyCal lback X509I ssuerSerialBasedRequest request SignatureVeri ficationKeyCallback X 509IssuerSerialBasedRequest cb getRequest locate and setx509Certificate on the request else throw unsupported else if Ccallbacks i instanceof SignatureKeyCallback SignatureKeyCallback cb SignatureKeyCal lback callbacks i if cb getRequest instanceof SignatureKeyCal lback DefaultPrivKey CertRequest default priv key cert req SignatureKeyCallback DefaultPrivKeyCer tRequest request SignatureKeyCal lback DefaultPrivKe yCertRequest cb getRequest locate and set default privateKey and X509Certificate on request else if cb getRequest instanceof SignatureKeyCallback AliasPrivKeyCertR equest Alias pr
121. 17 However you do not save this object You create the object only for the purposes of the search after which it disappears You do not 41 42 DEVELOPING CLIENTS FOR THE SERVICE REGISTRY need authorization from the Registry to create an object but you must have authorization to save it Note At this release you do not need authorization from the Registry to save objects Creating Objects A client creates an object and populates it with data before publishing it You can create and publish any of the following types of RegistryObject e AdhocQuery e Association e ClassificationScheme e Concept e ExternalLink e ExtrinsicObject e Federation e Organization e RegistryPackage e Service e Subscription e User The following types of RegistryObject cannot be published separately but you can create and save them as part of another object e Classification any RegistryObject e ExternalIdentifier any RegistryObject e ServiceBinding Service e Slot any RegistryObject e SpecificationLink ServiceBinding CREATING OBJECTS 43 Some objects fall into special categories An AuditableEvent is published by the Registry when an object has a change in state A Notification is published by the Registry when an Audi tableEvent that matches a Subscription occurs A Registry can be published only by a user with the role Registry Administrator The subsections that follow describe first the tasks commo
122. 200 WSDL files storing as extrinsic objects 62 WSS implementation 130 X XML digital signatures 130 encryption 130 XML and Web Services Security security configuration files 135 See XWS Security XML Digital Signature 225 230 See DSig XML Encryption See XML Enc XML Enc 130 132 137 211 INDEX 135 XWS Security 127 205 framework 128 method level 223 sample applications 174 JAAS 226 sample programs 128 schema 136 fomal 103 security configuration files 135 schema 139 troubleshooting 200
123. 230 241 248 255 259 263 sample programs XWS Security 128 saveObjects method LifeCycleM anager interface 56 saveOrganizations method Busi 132 INDEX nessLifeCycleManager interface 56 saving registry objects 294 56 SAX 87 schema XWS Security 139 103 Search menu 286 security end to end 127 message level 127 XML and Web Services 127 XWS Security 127 security configuration file creating 135 security configuration files 135 security tokens 128 SecurityConfiguration 136 SecurityEnvironmentHandler ele ment 136 SecurityEnvironmentHandlers writing 177 select command 97 service bindings adding specification links 301 adding to services 301 definition 54 Service element 136 Service interface 12 creating objects 54 deleting objects 67 retrieving objects 31 ServiceBinding interface 13 creating objects 54 retrieving objects 31 ServiceBinding objects using extrinsic objects as spec ification links 62 element services adding service bindings 301 set command 97 setAccessURI method Service Binding interface 55 setAreaCode method Telephone Number interface 51 setCountryCode method Tele phoneNumber interface 51 setDescription method Regis tryObject interface 51 setEmailAddresses method User interface 53 setFederated method QueryImp1 class 39 setFederation method QueryImp1 class 40 setKey method RegistryObject interface 45 setLid method RegistryObjec tImp1 class 45 setMimeType meth
124. 3 W3C Recommendation Extensible Markup Language XML 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 xm1 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 htm More efficient XML parsing with the Streaming API for XML http www 106 ibm com developerworks xml1 library x tipstx 126 STREAMING API FOR XML A Intoduction to XML and Web Services Sec unty Tiss addendum discusses using XML and Web Services Security XWS Security for message level security In message level security security informa tion is contained within the SOAP message and or SOAP message attachment which allows security information to travel along with the message or attach ment For example a portion of the message may be signed by a sender and encrypted fo
125. 4 x of the Java SDK configure a version of a JCE provider that supports RSA encryption Information on doing this is discussed in Configuring a JCE Provider 2 Make sure that you have a container installed For more information on containers read http java sun com webservices containers index html 3 Make sure that you have installed Java WSDP 1 6 If not you can down load the JWSDP from the following URL http java sun com webservices jwsdp index jsp 4 Set system properties as described in Setting System Properties 5 Read the information in Setting Up the Application Server For the Examples SETTING SYSTEM PROPERTIES Setting System Properties The asant or ant build files for the XWS Security samples shipped with this release rely on certain environment variables being set correctly Make sure that the following environment variables are set to the locations specified in this list If you are not sure how to set these environment variables refer to the file lt JWSDP_HOME gt xws security docs samples htm1 for more specific informa tion This file includes instructions for both the Unix and Microsoft Windows platforms Throughout this document instructions for running on the Unix plat form will be provided 1 Set JAVA_HOME to the location of your J2SE installation directory for example home lt your_name gt j2sdk1 4 2_04 2 Set JWSDP_HOME to the location of your Java WSDP 1 6 installation direc tory for exam
126. 6 by unique identifier 22 declarative 35 130 INDEX federated 39 iterative 36 predefined 287 stored 38 QueryLanguage scheme 18 QueryManager interface 4 quit command 94 classification R references creating 303 registries definition 1 ebXML 2 federations 39 UDDI 2 registry command line option 72 Registry database backing up and restoring 101 registry federations definition 2 registry objects 3 adding classifications 295 47 adding external identifiers 296 49 adding external links 296 50 adding names and descriptions 44 adding slots 297 50 approving deprecating or un deprecating 302 65 changing owner 87 creating 294 42 creating associations 303 57 creating identifiers 45 creating relationships 303 finding by classification 17 finding by external identifier 20 finding by external link 21 finding by key 22 finding by name 14 finding by type 16 finding by unique identifier 22 finding objects you published 22 finding with declarative que ries 35 finding with iterative queries 36 finding with stored queries 38 identifying 74 listing 92 organizing as registry packag es 64 removing 303 67 retrieving audit trail 33 retrieving classifications 26 retrieving external identifiers 26 retrieving external links 27 retrieving information about 24 retrieving logical identifier 25 retrieving name or description 24 retrieving slots 28 retrieving type 25 retrieving unique
127. 99 DSig 130 132 211 225 230 security configuration file 136 dumping requests 213 E ebXML registries 2 echo command 90 editor property displaying value 99 setting 97 email addresses adding to organizations or us ers 299 EmailAddress interface 13 retrieving objects 28 EmailType classification scheme 18 Encrypt element 136 EncryptedKeyCallback 182 encrypting SOAP messages 128 encrypting messages 137 encryption technologies 130 end to end security 127 ErrorHand1ingModel tion scheme 18 ErrorSeverityType classification scheme 18 EventType classification scheme 18 examples JAXR adding classifications to objects 48 adding external identifiers to objects 49 adding external links to ob jects 50 adding slots to objects 51 changing the state of regis try objects 66 classifica creating an extrinsic object as a specification link 63 creating associations 59 creating classification schemes 46 creating extrinsic objects 61 creating organization hier archies 53 creating organizations 52 creating registry packages 64 ctoring items in the reposi tory 61 declarative queries 36 deleting objects 68 displaying classification schemes and con cepts 19 federated queries 41 finding objects by classifi cation 19 finding objects by external identifier 20 finding objects by external link 21 finding objects by key 22 finding objects by name 16 finding objects by type 16 finding objects by unique i
128. APMessage and verify the security in an inbound SOAPMessage Because some of the Java standards for XWS Security technologies are currently undergoing definition under the Java Community Process the security solution that is provided in Java WSDP 1 6 is based on non stan dard APIs which are subject to change with new revisions of the technol ogy To insulate stand alone XWS Security users from the possible changes in the internal APIs this release includes a sample interface definition that abstracts out some of the internal implementation details Samples containing code for using these APIs are included with this release in the directory lt JWSDP_HOME gt xws security samples api sample Read XWS Security APIs Sample Application for more information on this sample application 131 132 INTRODUCTION TO XML AND WEB SERVICES SECURITY On Which Technologies Is XWS Sec unty Based XWS Security APIs are used for securing Web services based on JAX RPC and on stand alone applications based on SAAJ This release of XWS Security is based on standard XML Digital Signature and non standard XML Encryption APIs which are subject to change with new revisions of the technology As stan dards are defined in the Web Services Security space the non standard APIs will be replaced with standards based APIs JSR 105 XML Digital Signature APIs are included in this release of the Java WSDP JSR 105 is a standard API in progress at Proposed
129. AXR API to access a registry through 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 a class of registry providers that are based on a common specification This guide does not describe how to implement a JAXR provider 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 The most basic interfaces in the javax xml1 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 DEVELOPING CLIENTS FOR THE SERVICE REGISTRY The primary interfaces also part of the javax xml registry package are e QueryManager and BusinessQueryManager which allow the client to search a registry for information in accordance with the javax xml reg istry i
130. Association object and use it to specify a relationship between any two objects The ebXML specification specifies an Association Type classification scheme that contains a number of canonical concepts you can use when you create an Association You can also create your own concepts within the AssociationType classification scheme if none of the canonical ones are suitable 58 DEVELOPING CLIENTS FOR THE SERVICE REGISTRY The canonical association types are as follows AccessControlPolicyFor Affiliatedwith which has the subconcepts EmployeeOf and MemberOf Contains ContentManagementServiceFor EquivalentTo Extends External lyLinks HasFederationMember HasMember Implements InstanceOf InvocationControlFileFor which has the subconcepts Cataloging ControlFileFor and ValidationControlFileFor OffersService OwnerOf RelatedTo Replaces ResponsibleFor Submi tterOf Supersedes Uses The Registry uses some of these association types automatically For example when you add a Service to an Organization the Registry creates an OffersService association with the Organization as the source and the Ser vice as the target Associations are directional each Association has a source object and a target object Establishing an association between two objects is a three step process 1 Find the AssociationType concept you wish to use or create one 2 Use the LifeCycleManager createAssociation method to create the association
131. C provider s main class is org abc ABCProvider add this line security provider 2 org abc ABCProvider Make sure that the Sun security provider remains at the highest prefer ence with a value of 1 security provider 1l sun security provider Sun Adjust the levels of the other security providers downward so that there is only one security provider at each level SETTING UP THE APPLICATION SERVER FOR THE EXAMPLES The following is an example of a java security file that provides the nec essary JCE provider and keeps the existing providers in the correct loca tions security provider 1l sun security provider Sun security provider 2 org abc ABCProvider security provider 3 com sun net ssl internal ss1 P rovider security provider 4 com sun rsajca Provider security provider 5 com sun crypto provider SunJCE security provider 6 sun security jgss SunProvider 5 Save and close the file 6 Restart the Application Server or other container Setting Up the Application Server For the Examples To set up the container for running the XWS Security sample applications included with this release you need to specify on which container you are run ning the asant or ant build targets as discussed in Setting Build Properties and you must point the container to the keystore and truststore files to be used to run the XWS Security sample applications For the sample applications these are the keystore and truststore files included in the
132. CLASSES 37 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 java math 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 USING JAXB The ObjectFactory java code looks like this package prim
133. Finding Objects by Classification To find objects by classification you establish the classification within a particu lar classification scheme and then specify the classification as an argument to the BusinessQueryManagerImp1 findObjects method To do this you first find the classification scheme and then create a Classifica tion object to be used as an argument to the findObjects method or another finder method The following code fragment finds all organizations that correspond to a particu lar classification within the ISO 3166 country codes classification system main tained by the International Organization for Standardization ISO See http www iso org iso en prods services iso3166ma index html for details This classification scheme is provided in the sample database included with the Registry ClassificationScheme cScheme bqm findClassi ficationSchemeByName null 7 so ch 3166 1999 Classification classification blcm createClassification cScheme United States US Collection classifications new ArrayList classifications add classification perform query BulkResponse response bqm findObjectsC Organization null null classifications null null null Collection orgs response getCollection The ebXML Registry Information Model Specification requires a set of canoni cal classification schemes to be present in an ebXML registry Each scheme also has a set of required concepts cal
134. I to change the output encoding used during these marshal operations Client appli cations are expected to supply a valid character encoding name as defined in the W3C XML 1 0 Recommendation http ww w3 org TR 2000 REC xml 20001006 charencoding and supported by your Java Platform Client applications are not required to validate the Java content tree prior to call ing one of the marshal APIs 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 Different JAXB Providers can support marshalling invalid Java con tent trees at varying levels however all JAXB providers must be able to marshal a valid content tree back to XML data A JAXB provider must throw a Marshal Exception when it is unable to complete the marshal operation due to invalid content Some JAXB providers will fully allow marshalling invalid content oth ers will fail on the first validation error MORE ABOUT VALIDATION Table 1 2 shows the properties that Table 1 2 Marshaller Properties Property jaxb encoding the Marshaller class supports Value must be a java lang String the output encoding to use when marshalling the XML data The Marshal ler will use UTF 8 by default if this property is not specified jaxb formatted output Value must be a java lang Boolean controls whether or not the Marshal ler will format the resulting XML data with line breaks a
135. INE EXAMPLE 73 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 MyDatatypeC onverter Class The lt JWSDP_HOME gt jaxb samples 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 javaType 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 74 USING JAXB public static String printIntToInteger int value BigInteger result BigInteger valueOf value return DatatypeConverter printInteger result
136. If the application runs successfully you will see a message similar to the follow ing The final response will have Sun Microsystems Scenario lt scenario number gt echo java java java java Running the client program Sending Message Start Sending Message End Received Message Start Received Message End You will see similar messages in the server log files which are located in the fol lowing files lt SJSAS_HOME gt domains lt domain name gt logs server log lt TOMCAT_HOME gt logs launcher server log lt SJISWS_HOME gt lt Virtual Server Dir gt logs errors SAML SAMPLE APPLICATION 249 SAML Sample Application The samlinterop sample application demonstrates support for OASIS WSS SAML Token Profile 1 0 in XWS Security Security Assertion Markup Lan guage SAML assertions are used as security tokens SAML provides a means by which security assertions about messages can be exchanged between commu nicating service endpoints SAML is also considered important for promoting interoperable Single Sign On SSO and Federated Identity This release JWSDP 1 6 adds partial support for SAML Token Profile 1 0 This sample application was used as Sun s entry in a virtual interoperability demonstration sponsored by OASIS This sample implements three out of the four interop scenarios required by the event and described in the WSS SAML Interop Scenarios document The
137. MLEvent 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 required 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 107 Sun s Steaming Parser Implementation The JWSDP 1 6 includes an Early Access EA release of 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 l
138. ManagerURL Same as the specified queryManagerURL Specifies the URL of the life cycle manager service value within the target registry provider for registry updates Obtaining and Using a RegistryService 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 Typically a client obtains a BusinessQueryManager object and either a Life CycleManager or a BusinessLifeCycleManager object from the RegistrySer vice object If it is using the Registry for simple queries only it may need to obtain only a BusinessQueryManager object 10 DEVELOPING CLIENTS FOR THE SERVICE REGISTRY Querying a Registry This section describes the interfaces and methods JAXR provides for querying a registry It covers the following topics Using iterative queries Basic Query Methods JAXR Information Model Interfaces Finding Objects by Name Finding Objects by Type Finding Objects by Classification Finding Objects by External Identifier Finding Objects by External Link Finding Objects by Unique Identifier Finding Objects You Published Retrieving Information About an Object Using Declarative Queries Invoking Stored Queries Querying a Registry Federation B
139. NFIGURATION FILE SCHEMA 141 lt Port name port name conformance bsp gt lt Operation name op name gt lt SecurityConfiguration gt lt Operation gt lt Port gt lt SecurityEnvironmentHandler gt handler classname lt SecurityEnvironmentHandler gt lt Operation name operation_name gt lt SecurityConfiguration gt lt Operation gt lt Timestamp id unique_policy_identifier timeout 300 gt lt UsernameToken id unique_policy_identifier name user_name User name and password can also be obtained dynamically from the SecurityEnvi ronment password password useNonce true false digestPassword true false gt lt RequireUsernameToken id unique_policy_identifier nonceRequired C true false passwordDigestRequired true false maxClockSkew 60 timestampFreshnessLimit 300 maxNonceAge 900 gt lt Encrypt id unique_policy_identifier gt Key Bearing Token lt KeyEncryptionMethod algorithm http www w3 org 2001 04 xmlenc rsa oaep mgflp http www w3 org 2001 04 xmlenc kw tripledes http www w3 org 2001 04 xmlenc kw aes128 http www w3 org 2001 04 xmlenc kw aes256 http www w3 org 2001 04 xmlenc rsa 142 INTRODUCTION TO XML AND WEB SERVICES SECURITY 1_5 gt lt DataEncryptionMethod algorithm C http ww w3 org 2001 04 xmlenc aes128 cbc http www w3 org 2001 04 xmlenc tripledes cbc
140. OR 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 JWSDP_HOME gt jaxb samples fix collides binding xjb binding dec larations file resolves the conflicts in examples xsd by means of several custom izations 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 bindings 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 BIND CHOICE EXAMPLE 83 identifier representing a specific XML symbol space this single customization resolves all name col
141. Phone areaCode telephonel areaCode The area code of the first TelephoneNumber countryCode telephonel countryCode The country code of the first TelephoneNumber extension telephonel extension The extension of the first TelephoneNumber number telephonel number The telephone number suffix not including the country or area code of the first TelephoneNumber The number is required it must be specified either on the command line or in a properties file URL telephonel URL The URL of the first TelephoneNumber the URL that can dial this num ber electronically telephone2 type The type of the second TelephoneNumber If a second TelephoneNumber is specified the type is required it must be specified either on the com 84 ADMINISTERING THE SERVICE REGISTRY mand line or in a properties file It can have any of the following values Beeper FAX HomePhone Mobi lePhone or Of ficePhone telephone2 areaCode The area code of the second TelephoneNumber telephone2 countryCode The country code of the second TelephoneNumber telephone2 extension The extension of the second TelephoneNumber telephone2 number The telephone number suffix not including the country or area code of the second TelephoneNumber If a second TelephoneNumber is specified the number is required it must be specified either on the command line or in a properties file telephone2 URL The URL of the second TelephoneNumber th
142. ReaderImpl1 class com sun xm1 stream XMLReaderImp1 1 class com sun xm1 stream XMLScanner class com sun xm1 stream XMLStreamFilterImp1 class com sun xml1 stream ZephyrParserFactory class com sun xm1 stream ZephyrwriterFactory class com sun xml stream dtd DTDGrammarUtil class com sun xm1 stream dtd nonvalidating DTDGrammar class com sun xml stream dtd nonvalidating DTDGrammar QNameHashtab le class com sun xm1 stream dtd nonvalidating XMLAttributeDecl class com sun xml stream dtd nonvalidating XMLElementDecl class com sun xm1 stream dtd nonvalidating XMLNotationDecl class com sun xml stream dtd nonvalidating XMLSimpleType class com sun xm1 stream events AttributeImpl class com sun xm1 stream events CharacterEvent class com sun xml stream events CommentEvent class com sun xm1 stream events DTDEvent class com sun xm1 stream events DummyEvent class com sun xm1 stream events EndDocumentEvent class com sun xm1 stream events EndElementEvent class com sun xm1 stream events EntityDeclarationImp1 class com sun xml1 stream events EntityReferenceEvent class com sun xm1 stream events LocationImp1 class com sun xml1 stream events NamedEvent class com sun xm1 stream events NamespaceImpl1 class com sun xml1 stream events NotationDeclarationImp1 class com sun xm1 stream events ProcessingInstructionEvent class com sun xm1 stream events StartDocumentEvent class com sun xml stream events StartElementEvent class com sun xml1 stream events XMLEventAl locatorImp1 clas
143. RegistryObject getClassifications method to retrieve a Collec tion of the object s classifications For each classification you can retrieve its name value and the classification scheme to which it belongs The following code fragment retrieves and displays an object s classifications Collection classifications object getClassifications Iterator classIter classifications iteratorQ while classIter hasNextQ Classification classification Classification classIter nextQ String name classification getName getValue System out printIn Classification name is name System out printIn Classification value is classification getValue Q ClassificationScheme scheme classification getClassificationScheme System out printIn Classification scheme for name is scheme getName getValueQ Some of the examples have a showClassifications method that uses this code See for example JAXRQueryByName java in Finding Objects by Name Example page 16 Retrieving the Extemal Identifiers foran Object Use the RegistryObject getExternalIdentifiers method to retrieve a Col lection of the object s external identifiers For each identifier you can retrieve its name value and the classification scheme to which it belongs For an exter nal identifier the method that retrieves the classification scheme is getIdenti ficationScheme The following code fragment retrieves and displays an obje
144. SAML INTEROP SAMPLE CONFIGURATION FILES 253 Holder Of Key Sample Configuration Files The security configuration pair hok saml client xm l and hok sam1 server xml enable the following tasks as required by Scenario 4 e Client contains a holder of key SAML assertion e Client has the assertion signed by the assertion issuer with an enveloped signature e Client includes the certificate used to verify the issuer signature in the assertion signature e Client signs the request body e Server verifies that a SAML assertion is received e Server verifies the signature e Server sends the response which does not contain a security header The hok saml client xm1 file looks like this lt xwss JAXRPCSecurity xmIns xwss http java sun com xml ns xwss config gt lt xwss Service gt lt xwss SecurityConfiguration dumpMessages true gt lt xwss Sign includeTimestamp false gt lt xwss SAMLAssertion type HOK gt lt xwss Target type qname gt http schemas xmlsoap org soap envelope Body lt xwss Target gt lt xwss Sign gt lt xwss Timestamp gt lt xwss SecurityConfiguration gt lt xwss Service gt lt xwss SecurityEnvironmentHandler gt sample SecurityEnvironmentHandler lt xwss SecurityEnvi ronmentHand1er gt lt xwss JAXRPCSecurity gt The hok saml server xm1 file looks like this lt xwss JAXRPCSecurity xmIns xwss http java sun com xml ns xwss config gt lt xwss Service gt lt x
145. SECURITY CONFIGURATION FILE ELEMENTS 167 The attributes of lt EncryptionTarget gt are described in Table 4 33 its sub ele ments are described in Table 4 34 Table 4 33 Attributes of EncryptionTarget Attributes of EncryptionTarget Description Indicates the type of the target value Default value is qname The list of allowed values for this attribute and their descrip tion is as follows 1 qname If the target element has a local name Name and a namespace URI some uri the target value is some uri Name 2 xpath Indicates that the target value is the xpath of the target element 3 uri If the target element has an id some id then the tar get value is some id This option is used to secure message attachments Indicates whether the complete element or only the contents need to be encrypted or is required to be encrypted The default value is true Relevant only for lt Encrypt gt and lt RequireEncryption gt targets contentOnly Indicates whether the value needs to be encrypted or is required to be encrypted The default value is true Required If true indicates that the security operation on the target ele ment is definitely required Default value is true Relevant only for lt RequireSignature gt and lt RequireEncryption gt tar gets enforce Table 4 34 Sub elements of EncryptionTarget Sub elements of EncryptionTarget Description Identifies the transform algorithm to be app
146. Services Security XWS Security e XML Digital Signature e Service Registry All of the examples for this tutorial are installed with the Java WSDP 1 6 bundle and can be found in the subdirectories of the lt JWSDP_HOME gt lt technol ogy gt samples directory where JWSDP_HOME is the directory where you installed the Java WSDP 1 6 bundle The J2EE 1 4 Tutorial opens with three introductory chapters that you should read before proceeding to any specific technology area Java WSDP users should look at Chapters 2 and 3 which cover XML basics and getting started with Web applications ABOUT THIS TUTORIAL When you have digested the basics you can delve into one or more of the fol lowing main XML technology areas e The Java XML chapters cover the technologies for developing applications that process XML documents and implement Web services components The Java API for XML Processing JAXP The Java API for XML based RPC JAX RPC SOAP with Attachments API for Java SAAJ The Java API for XML Registries JAXR e The Web tier technology chapters cover the components used in develop ing the presentation layer of a J2EE or stand alone Web application Java Servlet JavaServer Pages JSP JavaServer Pages Standard Tag Library JSTL JavaServer Faces Web application internationalization and localization e The platform services chapters cover system services used by all the J2EE component technologies Java WSDP users should look at
147. TED System out print objName deprecated else if CeType AuditableEvent EVENT_TYPE_UNDEPRECATED System out print objName undeprecated else if CeType AuditableEvent EVENT_TYPE_UPDATED System out print objName updated else if CeType AuditableEvent EVENT_TYPE_VERSIONED System out print objName versioned else if CeType AuditableEventImp1 EVENT_TYPE_APPROVED System out print objName approved else if CeType AuditableEventImp EVENT_TYPE_DOWNLOADED System out print objName downloaded else if CeType AuditableEventImp1 EVENT_TYPE_RELOCATED System out print objName relocated else System out printC Unknown event for objName System out printIn ae getTimestamp Q toString Some of the examples have a showAuditTrail method that uses this code See for example JAXRQueryByName java in Finding Objects by Name Example page 16 See Changing the State of Objects in the Registry page 65 for information on how to change the state of registry objects Retrieving the Version of an Object If you modify the attributes of a registry object the Registry creates a new ver sion of the object For details on how this happens see Changing the State of USING DECLARATIVE QUERIES Objects in the Registry page 65 When you first create an object it has a ver sion of 1 1 Note At this release versioning of objects
148. TION 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 2005 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 peu
149. TION TO XML AND WEB SERVICES SECURITY Figure 4 1 shows the XML schema The tables in Semantics of Security Configuration File Elements provide more information on the elements contained within the schema The following notations are used to describe the schema e means OR e amp means AND e means zero or more of these elements allowed e means 1 required more allowed e means zero or one element allowed e value means that this value is the default value for the element so spec ifying this attribute is optional Figure 4 1 XWS Security Abstract Configuration File Schema lt JAXRPCSecurity gt lt Service gt lt SecurityEnvironmentHandler gt lt JAXRPCSecurity gt lt Service name service_identifier id unique_identifier conformance bsp useCache false true gt lt SecurityConfiguration gt lt Port gt lt SecurityEnvironmentHandler gt lt Service gt lt SecurityConfiguration dumpMessages false true enableDynamicPolicy C false true gt SecurityConfigurationElements lt SecurityConfiguration gt SecurityConfigurationElements lt Timestamp gt lt SAMLAssertion type SV gt _ lt RequireSAMLAssertion type SV gt lt UsernameToken gt lt RequireUsernameToken gt lt RequireTimestamp gt lt OptionalTargets gt lt Sign gt lt Encrypt gt lt RequireSignature gt lt RequireEncryption gt XWS SECURITY CO
150. Table 4 40 Table 4 40 Attributes of KeyEncryptionMethod Attributes of KeyEncryptionMethod Description Specifies the KeyTransport KeyWrap algorithms to be used to encrypt decrypt a public key or secret key key used to encrypt the data respectively The default value is http www w3 org 2001 04 xml enc rsa oaep mgf1p Other options include http www w3 org algorithm 2001 04 xmlenc rsa 1_5 http www w3 org 2001 04 xmlenc kw triple des http ww w3 org 2001 04 xmlenc kw aes128 and http www w3 org 2001 04 xmlenc kw aes256 Sec untyEnvironmentHandler The lt SecurityEnvironmentHandler gt element specifies the implementation class name of the security environment handler Read Writing SecurityEnvironmentHandlers for more information on SecurityEnvironmentHandlers How Do I Specify the Security Configuration for the Build Files After the security configuration files are created you can easily specify which of the security configuration files to use for your application In the build proper ties file for your application create a property to specify which security config uration file to use for the client and which security configuration file to use for the server An example from the simple sample application does this by listing 171 172 INTRODUCTION TO XML AND WEB SERVICES SECURITY all of the alternative security configuration files and uncommenting only the configuration to be used T
151. 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 EXTERNAL CUSTOMIZE EXAMPLE 75 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 xm1 bind DatatypeConverter lt xsd simpleType name ZipCodeType gt lt xsd annotation gt lt xsd appinfo gt lt jxb javaType name int parseMethod javax xml 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 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 JWSDP_HOME gt jaxb samples external customize binding xjb This section compares t
152. U use required gt lt xsd complexType gt lt xsd element gt lt xsd sequence gt lt xsd complexType gt lt Stock Keeping Unit a code for identifying products gt lt xsd simpleType name SKU gt lt xsd irestriction 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 In this example the schema comprises similar to a DTD a main or root schema element and several child elements element complexType and simpleType Unlike a DTD this schema also specifies as attributes data types like decimal date fixed and string The schema also specifies constraints like pattern value minOccurs and positiveInteger among others In DTDs you can only specify data types for textual data PCDATA and CDATA XML schema sup ports more complex textual and numeric data types and constraints all of which have direct analogs in the Java language Note that every element in this schema has the prefix xsd which is associated with the W3C XML Schema namespace To this end the namespace declaration xmilns xsd http www w3 org 2001 XMLSchema is declared as an attribute to the schema element Namespace support is another important feature of XML schemas because it provides a means to differentiate between elements written against different schemas or used for varying purposes but which may happen to have the same name as other elements in a docu
153. WS Security 2 0 FCS later this year When this renaming occurs the wscompi le tool will be replaced and these steps and the build xm1 files for the sample applications will need to be modified accordingly The syntax for this option is as follows wscompile security location of security configuration fi Te For more description of the wscompile tool its syntax and examples of using this tool read http docs sun com source 817 6092 hmanlm wscompi le 1m htm Troubleshooting XWS Sec unty Applications This section lists some possible errors and the possible causes for these errors For more troubleshooting information read the online release notes at http java sun com webservices docs 1 6 xws security ReleaseNotes html TROUBLESHOOTING X WS SECURITY APPLICATIONS Error at XMLC ipher getinstance Unknown Source java Exception in thread main java lang Nul1PointerException java at com sun org apache xml security encryption XMLCipher getInstan ce Unknown Source Solution Configure a JCE provider as described in Configuring a JCE Provider Error UnsupportedC lassVersionEnor java lang UnsupportedClassVersionError com sun tools javac Main Unsupported major minor version 49 0 Solution Install version 1 4 2_04 or higher of Java 2 Standard Edition J2SE If you had an older version of the JDK you will also have to reinstall the Applica tion Server so that it recognizes this as the default version of t
154. a readnwrite EventProducerConsumer Compile and run readn write EventProducerConsumer java writer CursorWriter Compile and run writer CursorWriter java To run any of the Ant targets change to the lt JWSDP_HOME gt sjsxp samples directory and invoke the target you want for example cd jwsdp home sjsxp samples ant cursor CursorParse Note If the StAX JSR 173 API JAR file is not named jsr173_api jar or is not in the same directory as the sjsxp jar file you will get an error when you run the samples If this occurs you should tell Ant the location of the StAX APIs by overriding the stax api jar property as shown ant Dstax api jar lt JSR 173 API LOCATION gt cursor CursorParse If Ant cannot find the sjsxp jar file override the sjsxp jar property as shown SAMPLE XML DOCUMENT ant Dsjsxp jar sjsxp jar location cursor CursorParse Running the Samples Manually You can also run the samples manually To do so go to the lt JWSDP_HOME sjsxp samples directory and change to the directory that con tains the sample you want to run For example to run the CursorParse java sample 1 Change to the directory containing the CursorParse java file cd lt JWSDP_HOME gt sjsxp samples cursor 2 Compile CursorParse java javac classpath lib jsr173_api jar CursorParse java Note that if the jsr173_api jar is in your CLASSPATH you do not need to use the classpath option here 3 Run the CursorParse sam
155. a RegistryPackage that is a member of the registry RegistryPackage which is not itself a member of any RegistryPackage is registry userData and the locator for the folder1 RegistryPackage that is a member of the userData Regis tryPackage is registry userData folder1 If you used the root option to specify the RegistryPackage locator when you started the Admin Tool the locator value is relative to that root URN The URN of the RegistryPackage which must be a URN starting with urn Examples The following command changes the directory to the RegistryPackage with the URN urn uuid 92d3fd01 a929 4eba a5b4 a3f036733017 admin gt cd urn uuid 92d3fd01 a929 4eba a5b4 a3f036733017 The following command changes the directory to the location registry user Data myData admin gt cd registry userData myData chown Changes the owner of a RegistryObject Synopsis chown URN index Descnption The chown command changes the ownership of the objects selected with a pre ceding select command to the user specified by either the URN or the reference to the user s URN when listed by a preceding users command 88 ADMINISTERING THE SERVICE REGISTRY Only a user with the role of administrator can execute this command success fully Operands URN The User specified by the URN index A numerical reference to a URN for a user listed in a preceding users command Examples The following command changes the ownersh
156. able 4 23 Sub elements of RequireEncryption Continued Sub elements of RequireEncryption Description Indicates the certificate corresponding to the SAML assertion used for encryption Only one of the X509Token SAMLAs sertion and SymmetricKey elements may be present at a time SAMLAssertion Indicates the symmetric key corresponding to the private key used for encryption Only one of the X5 9Token SAMLAs sertion and SymmetricKey elements may be present at a time SymmetricKey Indicates the canonicalization algorithm applied to the CanonicalizationMethod i lt Encrypt gt element prior to performing encrypt calculations Indicates the encryption algorithm to be applied to the cipher DataEncryptionMethod data Identifies the resource that was expected to be encrypted Tar Target get has been deprecated and is only provided for backward compatibility EncryptionTarget Identifies the resource that was expected to be encrypted Require SAMLAssertion The lt RequireSAMLAssertion gt element is used when a Sender Vouches SV SAML assertion is required for all incoming messages If a SAML assertion is not present an exception is thrown Table 4 24 provides a description of its attributes Table 4 24 Attributes of Requires AMLAssertion Attributes of RequireSAMLAssertion Description id Identifier for an assertion Optional Defines an abstract identifier for the assertion issuing author
157. able 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 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 spec
158. aceSupport class com sun xml1 stream xerces uti 1 NamespaceSupport IteratorPrefix es class com sun xm1 stream xerces uti 1 NamespaceSupport Prefixes class com sun xml stream xerces util ObjectFactory class com sun xml stream xerces uti1 ObjectFactory ConfigurationErro r class com sun xml stream xerces uti1 ParserConfigurationSettings cla ss com sun xm1 stream xerces uti1l STAXAttributesImp1 class com sun xm1 stream xerces uti1 STAXAttributesImp1 Attribute cl ass com sun xml1 stream xerces util SecuritySupport class com sun xml1 stream xerces util SecuritySupport12 class com sun xm1 stream xerces uti1 SecuritySupport12 1 class com sun xm1 stream xerces uti1 SecuritySupport12 2 class com sun xm1 stream xerces uti1 SecuritySupport12 3 class com sun xm1 stream xerces uti1 SecuritySupport12 4 class com sun xm1 stream xerces uti1 ShadowedSymbolTable class com sun xm1 stream xerces uti1l SymbolHash class com sun xm1 stream xerces util SymbolHash Entry class com sun xm1 stream xerces util SymbolTable class com sun xm1 stream xerces util SymbolTable Entry class com sun xml1 stream xerces uti1l SynchronizedSymbolTable class com sun xml stream xerces util URI class com sun xm1 stream xerces uti 1 URI MalformedURIException class com sun xm1 stream xerces uti1l XMLAttributesImp1 class com sun xml1 stream xerces uti1 XMLAttributesImp1 Attribute cla ss com sun xm1 stream xerces uti1l XMLAttributesIteratorImp1 class com sun xml stream xerces uti1l XMLChar cla
159. ache ant bin ant emacs 4 Repeat these steps for each example Windows NT 2000 XP 1 Set the following environment variables set JAVA_HOME lt your J2SE installation directory gt set JWSDP_HOME lt your JWSDP installation directory gt 2 Change to the desired example directory For example to run the Unmarshal Read example cd lt JWSDP_HOME gt jaxb samples unmarshal read lt JWSDP_HOME gt is the directory where you installed the Java WSDP bun dle 3 Run ant JWSDP_HOME apache ant bin ant emacs 4 Repeat these steps for each 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 32 The methods used for building and processing the Java content tree are described in Basic Examples page 43 29 USING JAXB J AXB Compiler Options The JAXB schema binding compiler is located in the lt JWSDP_HOME gt jaxb bin directory There are two scripts in this directory 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 invoking the scripts without any options or with the help switch The syntax is as follows xjc options lt schema gt The xjc command line options are listed in Table 2 2 Table 2 2 xjc Command Line Options Option or Argument Description lt schema gt One or more schema files to compile Do not perfo
160. age 73 for an example of how lt javaType gt declarations and the DatatypeConverterInterface interface are implemented in a custom datatype converter class 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 primary 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 simp eType definitions on a global level use the typesafeEnumBase attribute in a lt globalBindings gt declaration as described Global Binding Declarations page 61 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 fo
161. ail id 105 e JSR 106 XML Digital Encryption APIs http www jcp org en jsr detail id 106 e Public Key Cryptography Standards PKCS http www rsasecurity com rsalabs pkcs index html e Java Authentication and Authorization Service JAAS http java sun com products jaas e WS I Basic Security Profile Version 1 0 http www ws i org Profiles BasicSecurityProfile 1 0 2005 01 20 html e Web Services Security SOAP Messages with Attachments SwA Profile 1 0 http www oasis open org committees download php 10090 wss swa profile 1 0 draft 14 pdf e Web Services Security SOAP Messages with Attachments SwA Profile 1 0 Interop 1 Scenarios http lists oasis open org archives wss 2004 10 pdf00003 pdf e Web Services Security Security Assertion Markup Language SAML Token Profile 1 0 http docs oasis open org wss oasis wss saml token profile 1 0 pdf e Web Services Security Security Assertion Markup Language SAML Interop Scenarios FURTHER INFORMATION 203 http www oasis open org apps org workgroup wss download php 701 1 wss saml interop1 draft 11 doc 204 INTRODUCTION TO XML AND WEB SERVICES SECURITY 5 Understanding and Running the XWS Sec unty Sample Applications Tiss addendum discusses the XML and Web Services Security XWS Secu rity sample applications that are shipped with Java WSDP 1 6 For each of the sample applications there is an explanation of what is being demonstrated how the application is se
162. ain the specified pattern where pattern is a pattern comprising literal characters and the special characters asterisk representing zero or more characters and question mark representing one and only one character You can specify this option more than once Operands pattern The files or folders to be copied specified by a pattern comprising literal characters and the special characters asterisk representing zero or more characters and question mark representing one and only one character You can specify more than one pattern 89 90 ADMINISTERING THE SERVICE REGISTRY Examples The following command copies the directory mydir to the Registry to be owned by the user with the number 4 in a preceding users command admin gt cp owner 4 mydir The following command copies the directory mydir to the Registry excluding files and directories that end with the string z or c admin gt cp mydir exclude z exclude c echo Echoes a string Synopsis echo string Desc nption The echo command echoes the specified string to the output It is most useful when you specify it in the command option when you run the Admin Tool in batch mode Operand string A sequence of characters Example The following command prints the date and the result of the 1s command into a log file registry admin sh command echo date 1s gt admin log HELP 91 help Displays informatio
163. alid values within a classification scheme The classifica tion scheme is the parent in a tree hierarchy containing generations of child con cepts Table 7 3 describes the classification schemes provided by the Registry SEARCHING BY CLASSIFICATION 289 specifications Many of the terms in this table are defined in the Registry specifi cations Table 7 3 Classification Scheme Usage Classification Scheme Name AssociationType Frequently Description or Purpose Defines the types of associations between RegistryObjects Used as the value of the associationType attribute of an Asso ciation instance to describe the nature of the association ContentManagementService Defines the types of content management services Used in the configuration of a content management service such as a val idation or cataloging service DataType Frequently Defines the data types for attributes in classes defined by this document Used as the value of the slotType attribute of a Slot instance to describe the data type of the Slot value DeletionScopeType Occasionally Defines the values for the deletionScope attribute of the RemoveObjectsRequest protocol message EmailType Rarely Defines the types of email addresses ErrorHandlingModel Rarely Defines the types of error handling models for content management services ErrorSeverityType Rarely Defines the different error severity types encountered by the Regi
164. ally take one or more parameters that set some of the attributes of the object For example the createOrganization method sets the name of the organization Organization org blcm createOrganization MyOrgName On the other hand the createExtrinsicObject method takes a DataHandler argument that sets the repository item for the extrinsic object Adding Names and Descriptions to Objects For all objects you can set the name and description attributes by calling setter methods These attributes are of type InternationalString An Inter nationalString includes a set of LocalizedString objects that allow users to display the name and description in one or more locales By default the Inter nationalString value uses the default locale For example the following fragment creates a description for an organization that uses two localized strings one in the language of the default locale and one in French Canada InternationalString is blcm createInternationalStringC What We Do Locale loc new LocaleC fr CA LocalizedString 1s blcm createLocalizedString loc ce que nous faisons is addLocalizedString 1s org setDescription is CREATING OBJECTS Identifying Objects As stated in Finding Objects by Unique Identifier page 22 every object in the Registry has two identifiers a unique identifier and a logical identifier If you do not set these identifiers when you create the object the Registry generates a
165. alue Embedded gt lt xs enumeration value I ssuerSerialNumber gt lt xs restriction gt lt xs simpleType gt lt xs attribute gt lt xs complexType gt lt xs complexType name Target_T gt lt xs simpleContent gt lt xs extension base xs string gt FORMAL SCHEMA DEFINITION 113 lt xs attribute name type use optional default qname gt lt xs simpleType gt lt xs restriction base xs string gt lt xs enumeration value qname gt lt xs enumeration value uri gt lt xs enumeration value xpath gt lt xs restriction gt lt xs simpleType gt lt xs attribute gt lt xs attribute name contentOnly type xs boolean use optional default true gt lt xs attribute name enforce type xs boolean use optional default true gt lt xs extension gt lt xs simpleContent gt lt xs complexType gt lt xs complexType name SignatureTarget_T gt lt xs sequence minOccurs 0 maxOccurs 1 gt lt xs element name DigestMethod type DigestMethod_T minOccurs 0 maxOccurs 1 gt lt xs element name Transform type Transform_T minOccurs 0 maxOccurs unbounded gt lt xs sequence gt lt xs attribute name type use optional default qname gt lt xs simpleType gt lt xs restriction base xs string gt lt xs enumeration value qname gt lt xs enumeration value uri gt lt xs enumeration value xpath gt lt xs restriction gt lt xs simpleType gt lt xs a
166. alue for the individual que ries Increment the startIndex field at each loop iteration for Cint i 0 i lt 100 i maxResults Execute query with iterative query params Query query dqm createQuery Query QUERY_TYPE_SQL queryStr iterativeQueryParams startIndex i BulkResponse br dqm executeQuery query null jiterativeQueryParams Collection objects br getCollection retrieve individual objects The Registry is not required to maintain transactional consistency or state between iterations of a query Thus it is possible for new objects to be added or existing objects to be removed from the complete result set between iterations 38 DEVELOPING CLIENTS FOR THE SERVICE REGISTRY Therefore you may notice that a result set element is skipped or duplicated between iterations Using Iterative Queries Example For an example of the use of an iterative query see lt INSTALL gt registry sam ples query iterative src JAXRQueryIterative java This program finds all registry objects whose names match a given string and then iterates through the first 100 of them To run the example follow these steps 1 Go to the directory lt INSTALL gt registry samples query iterative 2 Type the following command specifying a string value ant run Dname string Invoking Stored Queries The implementation specific AdhocQueryImp1 class which extends Registry ObjectImp1 allows you to invoke queries that are s
167. ame ShipTo type USAddress gt lt xsd element name billTo 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 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 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 gt lt xsd simpleType gt lt xsd restriction base xsd positiveInteger gt 15 BINDING XML SCHEMA TO JAVA CLASSES WITH JAXB 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 SK
168. ame of the AttachmentPart Auto generated CIDs in JAX RPC following the form lt partname gt lt UUID gt lt Domain gt The special value cid can be used to refer to all attachments of a SOAPMessage The attributes of lt SignatureTarget gt are described in Table 4 31 its sub ele ments are described in Table 4 32 Table 4 31 Attributes of SignatureTarget Attributes of SignatureTarget Description Indicates the type of the target value Default value is qname The list of allowed values for this attribute and their descrip tion is as follows 1 qname If the target element has a local name Name and a namespace URI some uri the target value is some uri Name 2 xpath Indicates that the target value is the xpath of the target element 3 uri If the target element has an id some id then the tar get value is some id This is the option that is used to secure message attachments Indicates whether the value needs to be encrypted or is required to be encrypted The default value is true Rele vant only for lt Encrypt gt and lt RequireEncryption gt targets If true indicates that the security operation on the target ele ment is definitely required Default value is true Relevant only for lt RequireSignature gt and lt RequireEncryption gt tar gets enforce Table 4 32 Sub elements of SignatureTarget Sub elements of SignatureTarget Description Identifies the digest algorithm to be applied
169. aming API forXML ssssssnnssnnsna Ol Why StAX 87 Streaming Versus DOM 88 Pull Parsing Versus Push Parsing 89 StAX Use Cases 89 Comparing StAX to Other JAXP APIs 90 StAX API 91 Cursor API 91 Iterator API 92 Choosing Between Cursor and Iterator APIs 97 CONTENTS Using StAX 99 StAX Factory Classes 99 Resources Namespaces and Errors 101 Reading XML Streams 102 Writing XML Streams 105 Sun s Streaming Parser Implementation 107 SJSXP JAR Files 107 Reporting CDATA Events 108 SJSXP Factories Implementation 108 Sample Code 109 Configuring Your Environment for Running the Samples 109 Running the Samples 110 Sample XML Document 111 CursorParse java 112 CursorApproachEventObject java 114 EventParse java 115 CursorWriter java 118 MyStreamFilter java 119 EventProducerConsumer java 122 Further Information 125 Chapter4 Introduction to XMLand Web Services Security 127 Overview 128 Does XWS Security Implement Any Specifications 130 On Which Technologies Is XWS Security Based 132 Interoperability with Other Web Services 133 What is the X WS Security Framework 134 Configuring Security Configuration Files 135 Understanding Security Configuration Files 135 XWS Security Configuration File Schema 139 Semantics of Security Configuration File Elements 145 How Do I Specify the Security Configuration for the Build Files 171 Are There Any Sample Applications Demonstrating XWS Security 174 Writing SecurityEnvironmentHandlers 177
170. an X 509 certificate is present in an incoming message in the form of a BinarySecuri tyToken Request Inner Classes Defined Methods in the Request Classes 189 Dynamic Policy Callback This callback is intended for dynamic policy resolution Dynami cPolicyCal1lback is made by the XWS runtime to allow the application and or handler to decide the incoming and or outgoing SecurityPolicy at runt ime When the SecurityPolicy set on the callback is a Dynami cSecurityPolicy the Call backHand1ler is expected to set a com sun xml wss impl c onfiguration Message Policy instance as the resolved policy The Mes sagePolicy instance can contain policies generated by the PolicyGenerator obtained from the Dynamic SecurityPolicy 190 INTRODUCTION TO XML AND WEB SERVICES SECURITY The following code snippet shows the handle method skeleton for an applica tion s SecurityEnvi ronmentHand er that handles all the mandatory Callbacks except UsernameCallback and PasswordCallback and associated Requests defined by XWS Security A particular application may choose to throw an UnsupportedCal 1backException for any of the Callbacks or its Requests that it cannot handle The UsernameCal 1back and PasswordCal lback are useful for obtaining a username password pair at run time and are explained later in this section Note In this release of XWS Security users will have to ensure that the Securi tyEnvi ronmentHand
171. an use the mutator methods to set content on it Note The JAXB provider implementation must generate a class in each package that contains all of the necessary object factory methods for that package named ObjectFactory as well as the newInstance javaContentInterface method More About Marshalling The Marshal ler class in the javax xml bind package provides the client appli cation the ability to convert a Java content tree back into XML data There is no difference between marshalling a content tree that is created manually using the factory methods and marshalling a content tree that is the result an unmarshal operation Clients can marshal a Java content tree back to XML data to a 10 BINDING XML SCHEMA TO JAVA CLASSES WITH JAXB java io OutputStream or a java io Writer The marshalling process can alternatively produce SAX2 event streams to a registered ContentHandler or produce a DOM Node object A simple example that unmarshals an XML document and then marshals it back out is a follows JAXBContext jc JAXBContext newInstance com acme foo unmarshal from foo xml Unmarshaller u jc createUnmarshallerQ FooObject fooObj FooObject u unmarshal new File foo xml marshal to System out Marshaller m jc createMarshaller m marshal fooObj System out By default the Marshal ler uses UTF 8 encoding when generating XML data to a java io OutputStream or a java io Writer Use the setProperty AP
172. an end to end security framework that provides support for intermediary security processing Message integrity is provided by using XML Signature in conjunction with security tokens to ensure that mes sages are transmitted without modifications Message confidentiality is granted by using XML Encryption in conjunction with security tokens to keep portions of SOAP messages confidential In this release the XWS Security framework provides the following options for securing JAX RPC applications e XML Digital Signature DSig This implementation of XML and Web Services Security uses JSR 105 XML Digital Signature APIs for signing and verifying parts of a SOAP message or attachment JSR 105 can be viewed at http www jcp org en jsr detail id 105 Samples containing code for signing and or verifying parts of the SOAP message are included with this release in the directory lt JWSDP_HOME gt xws security samples simple Read Simple Security Configurations Sam ple Application for more information on these sample applications e XML Encryption XML Enc This implementation of XML and Web Services Security uses Apache s XML Enc implementation which is based on the XML Encryption W3C standard This standard can be viewed at http www w3 org TR xmlenc core Samples containing code for encrypting and or decrypting parts of the SOAP message are included with this release in the directory lt JWSDP_HOME gt xws security samples simple Read
173. and set the soap message to be processed ProcessingContext context new ProcessingContext context setSOAPMessage msg secure the message SOAPMessage secureMsg cprocessor secureOutbound Message context verify the secured message context new ProcessingContextQ context setSOAPMessage secureMsg SOAPMessage verifiedMsg null try verifiedMsg sprocessor verifyInboundMessage con text System out printinC nRequester Subject SubjectAccessor getRequesterSubject context catch Exception ex ex printStackTrace context getSOAPMessage writeTo System out 236 UNDERSTANDING AND RUNNING THE XWS SECURITY SAMPLE APPLICATIONS The API Sample Securty Configuration Files The client com sun wss sample Client code uses the XwSSProcessor APIs to secure SOAP messages according to the security policy inferred from the SecurityConfiguration with which this XwSSProcessor was initialized The api sample contains many different example security configuration files The following pairs should be used when specifying the client and server configura tion files in build properties The client configuration to specify is listed first the server configuration second e sign rsign xml sign rsign xml e username xml username xml e encryptvl xml encryptv1 xm e encryptv2 xml encryptv2 xm1 e signvl xml signvl xml e signv2 xml signvl xml e signv3 xml signv1 xml e signv4 xml sign
174. and supported meth ods Table 441 provides a brief summary of all the mandatory Callback classes and their associated Request types Table 4 41 Summary of Callback classes and their Request types Callback Signature Key Callback Description Used by XWS Security run time to obtain the private key to be used for signing the corresponding X 509 certifi cate There are two ways in which an application can sup ply the private key and certif icate information 1 Lookup a keystore using an alias 2 Obtain the default private key and certificate from the container environment in which the application is run ning 3 Obtain the private key and certificate given the public key This kind of request is used in scenarios where the public key appears as a Key Value under a ds KeyInfo and needs to be used for sign ing Accordingly there are three Request inner classes with which the SignatureKey Callback can be initialized Request Inner Classes Defined 1 AliasPrivKeyC ertRequest A Callback initialized with this request should be handled if the private key to be used for signing is mapped to an alias 2 Default PrivKeyCertRe quest A Callback initialized with this request should be han dled if there s some default private key to be used for signing 3 Publ icKey BasedPri vateKeyCertReque st A callback initial ized with this request should be handled if the private key to be used for s
175. ang String getPassword public java lang String getUsername public java lang String getDigestQ public java lang String getNonce public java lang String getCreated 186 INTRODUCTION TO XML AND WEB SERVICES SECURITY Table 4 41 Summary of Callback classes and their Request types Continued Request Inner Methods in the Request Callback Description Classes Defined Classes To supply the user name for the UsernameToken at run time It contains the follow ing two methods public void setUser name String username public String getUser name Username Callback Refer to the ClientSecu rityEnvironmen tHandler of the jaas samp1e located in lt JWSDP_HOME gt xws secu rity samples jaas sam ple src com sun xm1 wss sample for more details on using the Usern ameCal lback To supply the password for the username token at run time It contains the follow ing two methods public void setPass word String password public String getPass Pass word word Refer to the ClientSecu Callback rityEnvironmen tHandler of the jaas sample located in lt JWSDP_HOME gt xws secu rity samples jaas sam ple src com sun xm1l wss sample for more details on using the Pass wordCallback Table 4 41 Callback Property Callback WRITING SECURITYENVIRONMENTHANDLERS 187 Summary of Callback classes and their Request types Continued Description Optional callback to specify t
176. ant 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 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 is the output that is returned if you run the ant task in the lt JWSDP_HOME gt jaxb samples fix collides directory without specifying the binding param eter to the xjc task in the build xml file echo Compiling the schema w o external binding file name collision errors expected xjc Compiling file C Sun jwsdp 1 5 jaxb samples 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 82 USING JAXB 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 ERR
177. apped in a larger Java application that may provide UI features XML transformation functions data processing or whatever else is desired XML Input XML content that is unmarshalled as input to the JAXB binding frame Documents work that is an XML instance document from which a Java represen tation in the form of a content tree is generated In practice the term document may not have the conventional meaning as an XML instance document does not have to be a completely formed selfstanding document file it can instead take the form of streams of data passed between applications or of sets of database fields or of XML infosets in which blocks of information contain just enough information to describe where they fit in the schema structure In JAXB the unmarshalling process supports validation of the XML input document against the constraints defined in the source schema This validation process is optional however and there may be cases in which you know by other means that an input document is valid and so you may choose for performance reasons to skip validation during unmarshalling In any case validation before by means of a third party application or during unmarshalling is important because it assures that an XML document generated during marshalling will also be valid with respect to the source schema Validation is discussed more later in this chapter XML Output XML content that is marshalled out to an XML d
178. are the same However when an object exists in more than one version the unique iden tifiers are different for each version but the logical identifier remains the same See Retrieving the Version of an Object page 34 If you know the value of the unique identifier for an object you can retrieve the object by calling the QueryManager getRegistryObject method with the String value as an argument For example if bqm is your BusinessQueryMan ager instance and idString is the String value the following line of code retrieves the object RegistryObject obj bqm getRegistryObject idString Once you have the object you can obtain its type name description and other attributes Finding Objects by Unique Identifier Example For an example of finding objects by unique identifier see the example lt INSTALL gt registry samples query id src JAXRQueryBylId java which searches for objects that have a specified unique identifier To run the example follow these steps 1 Go to the directory lt INSTALL gt registry samples query id 2 Type the following command ant run Did urn_value For example if you specify the following ID you retrieve information on the ObjectType classification scheme urn oasis names tc ebxml regrep classificationScheme ObjectType Finding Objects You Published You can retrieve all objects that you published to the Registry or you can narrow this search to retrieve only the objects you published
179. area for the Organization click the Organizations tab The Organizations table appears Click Add A Details Panel window opens In the Name field type a name for the new organization Optionally type a description in the Description field Type values in the address fields All fields except Street are optional e Street Number e Street required e City e State or Province e Country e Postal Code Click Add to close the Details Panel window ADDING A SERVICE BINDING TO A SERVICE 301 The new version of the object appears in the Registry Objects area and the new Organization is created 7 Click Save in the Details area for the object Adding a Service Binding to a Service A Service normally has one or more service bindings To add a service binding to a Service follow these steps 1 In the Details area for the Service click the ServiceBindings tab The ServiceBindings table appears Click Add A Details Panel window opens In the Name field type a name for the service binding Optionally type a description of the service binding in the Description field In the Access URI field type the URL for the service binding 6 Click Add to close the Details Panel window The new version of the object appears in the Registry Objects area Click Save in the Details area for the object Adding a Specification Link to a Service Binding A ServiceBinding normally has a Specif
180. ase XMLEvent COMMENT return COMMENT case XMLEvent START_DOCUMENT EVENTPARSE JAVA 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 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 www 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 118 STREAMING API FOR XML CursoriWinterjava Located in the lt JWSDP_HOME gt sjsxp samples
181. asic Query Methods The simplest way for a client to use a registry is to query it for information about the objects and data in it The QueryManager BusinessQueryManager and Reg istryObject interfaces support a number of finder and getter methods that allow clients to search for data using the JAXR information model Many of the finder methods return a BulkResponse a collection of objects that meets a set of criteria specified in the method arguments The most general of these methods are as follows getRegistryObject and getRegistryObjects QueryManager methods that return one or more objects based on their type or unique identifier or return the objects owned by the caller for information on unique identifi ers see Finding Objects by Unique Identifier page 22 findObjects an implementation specific BusinessQueryManager method that returns a list of all objects of a specified type that meet the specified criteria JAXR INFORMATION MODEL INTERFACES Other finder methods allow you to find specific kinds of objects supported by the JAXR information model While a UDDI registry supports a specific hierarchy of objects organizations which contain users services and service bindings an ebXML registry permits the storage of freestanding objects of various types that can be linked to each other in various ways Other objects are not freestand ing but are always attributes of another object The BusinessQueryManager finder methods are
182. ate 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 import javax xml bind JAXBException import javax xml bind Marshaller import javax xml bind UnmarshalException import javax xml bind Unmarshaller import javax xml bind ValidationEvent import javax xml bind util ValidationEventCol lector import primer po 52 USING JAXB 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 ValidationEventHand1er 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
183. ations 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 60 CUSTOMIZE INLINE EXAMPLE 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 MyDatatypeCon 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 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 c
184. ations of the events for example public final staticString getEventTypeString CinteventType 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 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 114 STREAMING API FOR XML 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 CursorpproachEventObjectjava Located in the lt JWSDP_HOME gt sjsxp samples cursor2event directory Cur sorApproachEventObject java demonstrates how to get information 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 easi
185. ay repeat the option or operand Anything else is literal text that you must include when running the command add association Adds an Association object to the Registry Synopsis add association type association type sourceURN targetURN ADD ASSOCIATION 77 Description The add association command adds an Association object of the specified type to the Registry You can use any of the following types AccessControlPolicyFor AffiliatedWith which has the subconcepts EmployeeOf and MemberOf Contains ContentManagementServiceFor EquivalentTo Extends ExternallyLinks HasFederationMember HasMember Implements InstanceOf InvocationControlFileFor which has the subconcepts Cataloging ControlFileFor and ValidationControlFileFor OffersService OwnerOf RelatedTo Replaces ResponsibleFor SubmitterOf Supersedes Uses Options type The type of the Association object Operands sourceURN 78 ADMINISTERING THE SERVICE REGISTRY The URN of the source object targetURN The URN of the target object Example The following command all on one line creates a RelatedTo relationship between the objects with the two specified URNs admin gt add association type RelatedTo urn uuid ab80d8f7 3bea 4467 ad26 d04a40045446 urn uuid 7a54bbca 2131 4a49 8ecc e7b4ac86c4fd add user Adds a user to the Registry Synopsis add user edit load file firstName string lastName string middleName st
186. bar Unmarshaller u jc createUnmarshallerQ FooObject fooObj FooObject u unmarshal new File foo xml ok BarObject barObj BarObject u unmarshal new File bar xml ok MORE ABOUT MARSHALLING BazObject bazObj BazObject u unmarshal new File baz xml error com acme baz not in contextPath A client application may also generate Java content trees explicitly rather than unmarshalling existing XML data To do so the application needs to have access and knowledge about each of the schema derived ObjectFactory classes that exist in each of Java packages contained in the contextPath For each schema derived Java class there will be a static factory method that produces objects of that type For example assume that after compiling a schema you have a pack age com acme foo that contains a schema derived interface named Purchase Order To create objects of that type the client application would use the following factory method ObjectFactory objFactory new ObjectFactory com acme foo PurchaseOrder po objFactory createPurchaseOrder Note Because multiple ObjectFactory classes are generated when there are mul tiple packages on the contextPath if you have multiple packages on the contex tPath you should use the complete package name when referencing an ObjectFactory class in one of those packages Once the client application has an instance of the schema derived object it c
187. be initialized Note Additional Requests may be defined in a future release Request Inner Classes Defined 1 X509SubjectKeyId enti fierBase dRequest Request for an X 509 certifi cate whose X 509 SubjectKeyIden tifier value is given 2 X509IssuerSerial BasedRequest Request for an X 509 certificate whose issuer name and serial number values are given 3 PublicKeyBase dRequest Request for an X 509 certifi cate for a given public key Methods in the Request Classes The following two methods are present in all the Request classes of this Callback public void setx509Certificate X509Certificate cer tificate public X509Certificate getx509CertificateQ 182 INTRODUCTION TO XML AND WEB SERVICES SECURITY Table 4 41 Summary of Callback classes and their Request types Continued Callback Encryp tion Key Callback Description Obtains the certificate for key encryption or a symmet ric key for data encryption The three situations for which XWS Security would require this Callback for performing encryption 1 When the xwss Encrypt element contains an xwss X50 9Token child with certificateAlias attribute set to an alias The certificateAlias indi cates that a random symmet ric key is used for encryption of the specified message part and the certificate is then used to encrypt the random symmetric key to be sent along with the message 2 When the xwss Encrypt eleme
188. 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 277 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 XMLSignatureFactory by calling the following line of code XMLSignatureFactory factory XMLSignatureFactory getInstance DOM 276 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
189. been signed and then encrypted The certificate associated with the encryption is provided out of band to the requestor The certificate used to verify the signature is pro vided in the header The Response Body is not signed or encrypted There are two certificates in the request message One identifiers the recipient of the encrypted attachment and one identifies the signer 4 Scenario 4 Attachment Signature and Encryption with MIME Headers The SOAP request contains an attachment that has been signed and then encrypted The certificate associated with the encryption is provided out of band to the requestor The certificate used to verify the signature is pro vided in the header The Response Body is not signed or encrypted There are two certificates in the request message One identifies the recipient of the encrypted attachment and one identifies the signer This scenario dif fers from the first three scenarios in that it covers MIME headers in the signature and encryption This means that it uses the Attachment Com plete Signature Reference Transform and Attachment Complete Encrypt edData Type Aside from these two changes Scenario 4 is identical to Scenario 3 244 UNDERSTANDING AND RUNNING THE XWS SECURITY SAMPLE APPLICATIONS SwA Sample Configuration Filles The security configuration pair swa client xm1 and swa server xml are used to secure message attachments Each file contains the security configuration for each of t
190. bject for the repository item The LifeCycleMan ager createExtrinsicObject method takes a DataHandler argument To store a file in the repository for example first create a java io File object From the File object create a javax activation FileDataSource object which you use to instantiate the DataHandler object String filename MyFile xm1 File repositoryItemFile new File filename DataHandler repositoryItem new DataHandler new FileDataSource repositoryItemFile Next call createExtrinsicObject with the DataHandler as argument ExtrinsicObject eo blcm createExtrinsicObject repositorylItem eo setName My File STORING ITEMS IN THE REPOSITORY Set the MIME type of the object to make it accessible The default MIME type is application octet stream If the file is an XML file set it as follows eo setMimeType text xm1 Finally call the implementation specific ExtrinsicObjectImp1 setObject Type method to store the ExtrinsicObject in an appropriate area of the Regis try This method has the following signature public void setObjectType Concept objectType throws JAXRException The easiest way to find the appropriate concept for a file is to use the Explore feature of the Web Console Look under the ObjectType classification scheme for the various types of ExtrinsicObject concepts Specify the ID for the con cept as the argument to getRegistryObject then specify the concept as the argument to setObje
191. bjectKeyId entifierBase dRequest Request for a private key when the X 509 Subject KeyIdentifier value for a corre sponding X 509 certif icate is given 2 X509IssuerSerial BasedRequest Request for a private key when the issuer name and serial num ber values for a corre sponding X 509 certificate are given 3 X509CertificateB asedRequest Request for a private key when a corre sponding X 509 certif icate is given Methods in the Request Classes The following two methods are present in the X50 9SubjectKeyIdentifier BasedRequest X509IssuerSerialBasedReq uest and X509CertificateBasedRequ est Request classes of this Callback public void setPri vateKey PrivateKey pri vateKey public PrivateKey getPrivateKey 184 INTRODUCTION TO XML AND WEB SERVICES SECURITY Table 4 41 Summary of Callback classes and their Request types Continued Callback Decryp tion Key Callback C contin ued Description 3 When the EncryptedKey contains a wsse Direct ref erence to the key used for encrypting the symmetric key This means the X 509 certificate is present as a wsse BinarySecurityTo ken in the message For example when the sender specifies the attribute key Reference Type Direct on the xwss x509Token child of xwss Encrypt element 4 When the Encrypted Data contains a ds key Name reference to the symmetric key that was used for encryption For example when the sender
192. bjects in the Registry Removing Objects From the Registry and Repository Further Information ONAANNNAWN DDADDAUNMHMUNK BWWWWNHNNNN NRHP RPK HE APrAInNPOnNnrdtanNnNrRrOWAUNFANNF ON DFR OS CONTENTS Chapter9 Administering the Service Registry 69 About the Admin Tool Starting the Admin Tool Batch Mode Interactive Mode Admin Tool Command line Options Using the Admin Tool Permissions Displaying Exceptions Identifying Registry Objects The Effect of Locale on Specifying Names Case Sensitivity Using Admin Tool Commands add association add user cd chown cp echo help lcd Is pwd quit rm select set show users Other Administration Tasks Backing Up and Restoring the Database Appendix A A XWS Security Formal Schema Definition103 Formal Schema Definition 69 70 70 71 71 73 73 74 74 75 75 75 76 78 86 87 88 90 91 92 92 94 94 95 97 97 99 100 101 101 103 Appendix B SSXPJARFileS 0cce eee eee eee eee 115 sjsxp jar jsr173_api jar 115 119 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 not Custom of the Java WSDP v1 6 with the Sun Java System Application Server
193. bleJavaNamingConventions 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 Enumeration Binding Declarations page 66 for information about local ized mapping of simpleType definitions to Java typesafe enum classes typesafeEnumMemberName can be either generateError or generate Name The default value is generateError bindingStyle can be either elementBinding or modelGroupBinding The default value is elementBinding lt javaType gt can be zero or more javaType binding declarations See lt javaType gt Binding Declarations page 64 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 globalBindings gt declaration in any given schema or binding declarations file If one source schema includes or imports a second source schema the lt globalBindings 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 nameXmlTransform gt lt nameXmlTransform gt lt schemaBindings gt lt package name packageName lt javad
194. can have either of the following values HomeEmail or Of ficeEmai 1 email2 address The second email address email3 type The type of the second EmailAddress If a third EmailAddress is speci fied the type is required it must be specified either on the command line or in a properties file It can have either of the following values HomeEmail or Of ficeEmai 1 email3 address 86 ADMINISTERING THE SERVICE REGISTRY The third email address Examples The following command loads the User properties from the file Jane Smith properties in the user s home directory admin gt add user load JaneSmith properties The following command all on one line specifies the minimum properties required to create a User admin gt add user ln Smith postaltype Office street Smith Street phonetype Office number 333 3333 emailtype OfficeEmail emailaddress JaneSmith JaneSmith com cd Changes the RegistryPackage location Synopsis cd locator URN Description Change directory metaphorically to the RegistryPackage at the specified path or with the specified URN Change to a specified URN when there are multiple RegistryPackage objects with the same path for the current locale Operands locator The path of names of registry objects from the root of the repository to an object in the repository with each name preceded by a forward slash CHOWN 87 For example the locator for the userDat
195. cation developer can use the XML and Web Services Security framework and APIs The example applica tions can be found in the lt JWSDP_HOME gt xws security samples lt sample_name gt directory Before you can run the sample applications you ARE THERE ANY SAMPLE APPLICATIONS DEMONSTRATING X WS SECURITY must follow the setup instructions in Setting Up To Use XWS Security With the Sample Applications The sample applications print out both the client and server request and response SOAP messages The output from the server may be viewed in the appropriate container s log file The output from the client is sent to stdout or whichever stream is used by the configured log handler Messages are logged at the INFO level Note In some of the sample security configuration files no security is specified for either a request or a response In this case the response is a simple JAX RPC response When XWS Security is enabled for an application by providing the security option to wscompile and a request or response not containing a wsse Security Header is received the message WSS 202 No Security element in the message will display in the output to warn that a nonsecure response was received In these examples the server side code is found in the lt JWSDP_HOME gt xws security samples lt sample_name gt server src lt sample_name gt directory Client side code is found in the lt JWSDP_HOME gt xws security samples lt sample_nam
196. ce 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 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 Using the Service Registry Web Console Tins chapter describes the Web Console for the Service Registry the Regis try It contains the following sections e Getting Started With the Web Console e Searching the Registry e Publishing and Managing Registry Objects Getting Started Wit the Web Console The Web Console is a web based user interface that allows you to search the Registry and to publish content to the Registry and Repository This section describes the preliminary steps to follow before you can perform these opera tions e Starting the Web Console e Changing the Defaul
197. ce whose locale most closely matches the current locale not against all the multiple names for the registry object For example suppose the current RegistryPackage has a member object that has two names each associated with a different locale red in the en English locale and rouge in the fr French locale When the current locale is en the command 1s rouge does not display that member object but when the locale is fr or one of its variants then it does Case Sensitivity Command names and literal parameters that are recognized by the Admin Tool are not case sensitive For example 1s Ls and LS are equivalent Options to which you provide the value are passed literally to the code that uses the option Using Admin Tool Commands The following sections describe the available commands For each command the synopsis and the descriptions of the options and operands observe the follow ing typographical conventions e Italics indicate an option argument or operand that should be replaced by an actual value when you run the command e Curly braces delimit a choice of options or operands where you must include one of the options or operands The options or operands are sepa rated by a vertical bar e Square brackets delimit an option or operand or a choice of options or operands that may be omitted 75 76 ADMINISTERING THE SERVICE REGISTRY e Ellipses after an option or operand indicates that you m
198. choiceContentProperty true false 1 o J underscoreBinding asWordSeparator asCharInWord typesafeEnumBase typesafeEnumBase typesafeEnumMemberName generateName generateError enableJavaNamingConventions true false 1 o J bindingStyle elementBinding modelGroupBinding lt javaType gt lt javaType gt lt globalBindings gt e collectionType can be either indexed or any fully qualified class name that implements java util List e fixedAttributeAsConstantProperty can be either true false 1 or 0 The default value is false e generateIsSetMethod can be either true false 1 or The default value is false e enableFai1lFastCheck can be either true false 1 or 0 If enableFail FastCheck is true or 1 and the JAXB implementation supports this optional checking type constraint checking is performed when setting a 62 USING JAXB 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 bindingStyle is elementBinding Therefore if bindingStyle is speci fied as elementBinding then the choiceContentProperty must result in an invalid customization underscoreBinding can be either asWwordSeparator or asCharInword The default value is asWordSeparator ena
199. codebase by telling the compiler to reuse an existing imp1 runtime package 32 USING JAXB Table 2 2 xjc Command Line Options Continued Option or Argument Description Treat input schemas as W3C XML Schema default If you do not xml schema specify this switch your input schemas will be treated as W3C XML Schema Treat input schemas as RELAX NG experimental unsupported relaxng Support for RELAX NG schemas is provided as a JAXB Vendor Extension Treat input schemas as XML DTD experimental unsupported Support for RELAX NG schemas is provided as a JAXB Vendor Extension Display this help message The command invoked by the xjc sh and xjc bat scripts is equivalent to the Java command JAVA_HOME bin java jar JAXB_HOME 1lib jaxb xjc jar 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 Create Marshal Unmarshal Validate Validate On Demand the JAXB binding compiler gener ates a Java package named primer po containing eleven classes making a total of twelve classes in each of the basic examples Table 2 3 Schema Derived JAXB Classes in the Basic Examples Css Deseripton OOOO Public interface extending javax xml1 bind E ement primer po binds to the global schema element named comment Note Comment java that JAXB generates element interfaces for all global element declarati
200. command line option 72 locale command line option 72 locale property displaying value 99 locales effect on specifying names 75 setting 284 LocalizedString interface 14 logical identifiers retrieving 25 1s command 92 M method level security 223 N names of registry objects searching by 288 NodeType classification scheme 18 NotificationOptionType classifi cation scheme 18 O Oasis Web Services Security See WSS object types searching by 287 ObjectType classification scheme 18 Organization interface 12 creating objects 51 deleting objects 67 retrieving object attributes 28 retrieving parent and child ob jects 32 retrieving services and service bindings 31 organizations adding child organizations 300 adding email addresses 299 adding postal addresses 298 adding telephone numbers 298 adding users 299 INDEX 129 P PasswordCallback 186 PasswordValidationCallback 185 PersonName interface 14 PFX files 197 PhoneType classification scheme 18 PKCS 12 files 197 pkcs12import command 128 197 postal addresses adding to organizations or us ers 298 PostalAddress interface 14 retrieving objects 28 predefined queries 287 PrefixNamespaceMappingCall back 188 prerequisites xi printing the tutorial xv property values displaying 99 setting 97 PropertyCallback 187 providers JAXR 3 pwd command 94 Q queries basic methods 10 by classification 17 by external identifier 20 by external link 21 by name 14 by type 1
201. created and its properties set to comply with the schema constraints public static USAddress createUSAddress ObjectFactory objFactory String name String street String city String state String zip throws JAXBException create an empty USAddress objects USAddress address objFactory createUSAddress set properties on it address setName name address setStreet street address setCity city address setState state address setZip new BigDecimal zip return it USING JAXB return address 12 Similar to the previous step an empty ItemType object is created and its properties set to comply with the schema constraints public static Items ItemType createItemType ObjectFactory objFactory String productName BigInteger quantity BigDecimal price String comment Calendar shipDate String partNum throws JAXBException create an empty ItemType object Items ItemType itemType objFactory createItemsItemTypeQ set properties on it itemType setProductName productName itemType setQuantity quantity jtemType setUSPrice price itemType setComment comment jtemType setShipDate shipDate itemType setPartNum partNum return it return itemType 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 2002 09 24 05 00 gt lt shipTo gt
202. ct s external identifiers Collection exIds object getExternalidentifiersQ Iterator exIdIter exIds iterator while exIdIter hasNextQ ExternalIdentifier exId RETRIEVING INFORMATION ABOUT AN OBJECT 27 CExternalIdentifier exIdIter nextQ String name exId getName getValueQ System out printInC External identifier name is name String exIdValue exId getValueQ System out printInC External identifier value is exIdValue ClassificationScheme scheme exId getIdentificationScheme System out printInC External identifier classification scheme is scheme getName getValue Some of the examples have a showExternalIdentifiers method that uses this code See for example JAXRQueryByName java in Finding Objects by Name Example page 16 Retrieving the Extemal Links foran Object Use the RegistryObject getExternalLinks method to retrieve a Collection of the object s external links For each external link you can retrieve its name description and value For an external link the name is optional The following code fragment retrieves and displays an object s external links Collection exLinks obj getExternalLinks Iterator exLinkIter exLinks iteratorQ while CexLinkIter hasNextQ ExternalLink exLink ExternalLink exLinkIter nextQ String name exLink getName getValueQ if name null System out printIn External link name is name Str
203. ctType String conceptid urn oasis names tc ebxml regrep ObjectType RegistryObject ExtrinsicObject XML Concept objectTypeConcept Concept bqm getRegistryObject conceptId CCExtrinsicObjectImp1 eo setObjectType objectTypeConcept Finally you save the ExtrinsicObject to the Registry Collection extobjs new ArrayListQ extobjs add eo BulkResponse response blcm saveObjects extobjs The ExtrinsicObject contains the metadata and a copy of the file is stored in the repository If the Registry does not have a concept for the kind of file you want to store there you can create and save the concept yourself Creating an Extrinsic Object Example For an example of creating an extrinsic object see lt INSTALL gt registry sam ples publish extrinsic src JAXRPublishExtrinsicObject java This 61 62 DEVELOPING CLIENTS FOR THE SERVICE REGISTRY example publishes an XML file to the Registry To run the example follow these steps 1 Go to the directory lt INSTALL gt registry samples publish extrin sic 2 Type the following command ant run Using an Extrinsic Objectasa Specification Link You can publish an ExtrinsicObject by itself but it is also very common to create an ExtrinsicObject to use as the SpecificationLink object for a Ser viceBinding object see Creating Services and Service Bindings page 54 The ExtrinsicObject typically refers toa WSDL file 1 Create a SpecificationLink object
204. cters 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 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
205. cured and how to compile and run the application Introduction to XML and Web Services Security provides an introduction to how to use XWS Security in this release Setting Up To Use XWS Security With the Sample Applica tions provides information on how to configure your system to run the sample applications 205 206 UNDERSTANDING AND RUNNING THE XWS SECURITY SAMPLE APPLICATIONS The following sample applications are discussed in this chapter e Simple Security Configurations Sample Application e JAAS Sample Application e XWS Security APIs Sample Application e Soap With Attachments Sample Application e SAML Sample Application e Dynamic Policy Sample Application e Dynamic Response Sample Application Setting Up To Use XWS Sec unity With the Sample Applications This addendum discusses creating and running applications that use the XWS Security framework and deploying these applications onto the Sun Java System Application Server Platform Edition 8 1 For deployment onto other containers read the README txt file for the example applications for more information Follow these steps to set up your system to compile run and deploy the sample applications included in this release that use the XWS Security framework 1 Make sure that you have installed the Java 2 Platform Standard Edition version 1 4 2 or higher If not you can download the JDK from the follow ing URL http java sun com j2se If you are using version 1
206. curityEnvironmentHandler lt xwss SecurityEnvi ronmentHand1er gt lt xwss JAXRPCSecurity gt If you compare this security configuration file to the similar one in the simple sample as discussed in Adding a Username Password Token you ll see that this secu rity configuration file does not hard code the user name and password In this example the username and password are obtained by reading a system property username password that is configured in the build xml file of the jaas sam ple under the run sample target as a sysproperty The properties and a section of the target from this example are configured like this lt target name run sample depends clean prepare build server deploy forced build client description Runs the example client gt lt echo message Running the client class program gt lt java fork on classname client class gt lt sysproperty key java endorsed dirs value java endorsed dirs gt lt sysproperty key endpoint host value endpoint host gt lt sysproperty key endpoint port value endpoint port gt lt sysproperty key service url value service url gt lt sysproperty key username password value Ron noR gt The client side SecurityEnvironmentHandler of this sample is the entity that actually reads the system property at run time and populates the username and password Callback objects passed to it by the XWS Security run time A differ ent Sec
207. curs 0 maxOccurs unbounded gt lt xs sequence gt lt xs attribute name name use required gt lt xs simpleType gt lt xs restriction base xs string gt lt xs minLength value 1 gt lt xs restriction gt lt xs simpleType gt lt xs attribute gt lt xs attribute name conformance use optional gt lt xs simpleType gt lt xs restriction base xs string gt lt xs enumeration value bsp gt lt xs restriction gt FORMAL SCHEMA DEFINITION 105 lt xs simpleType gt lt xs attribute gt lt xs complexType gt lt xs complexType name Operation_T gt lt xs sequence gt lt xs element ref SecurityConfiguration minOccurs 0 maxOccurs unbounded gt lt xs sequence gt lt xs attribute name name use required gt lt xs simpleType gt lt xs restriction base xs string gt lt xs minLength value 1 gt lt xs restriction gt lt xs simpleType gt lt xs attribute gt lt xs complexType gt lt xs element name SecurityConfiguration type SecurityConfiguration_T gt lt xs complexType name SecurityConfiguration_T gt lt xs sequence gt lt xs group ref SecurityConfigurationElements minOccurs 0 maxOccurs unbounded gt lt xs sequence gt lt xs attribute name dumpMessages type xs boolean use optional default false gt lt xs attribute name enableDynamicPolicy type xs boolean use optional default false gt lt xs complexType gt lt xs group name SecurityCon
208. cuted with the exception of the OptionalTargets element Table 4 10 Attributes of SecurityConfiguration Attributes of Security Configuration Description If dumpMessages is set to true all incoming and outgoing dumpMessages messages are printed at the standard output The default value is false Optional SEMANTICS OF SECURITY CONFIGURATION FILE ELEMENTS 149 Table 4 10 Attributes of SecurityConfiguration Continued Attributes of SecurityConfiguration Description If enableDynamicPolicy is set to true all incoming and outgoing messages use a dynamic security policy The default value is false Optional For an example that uses this attribute see Dynamic Policy Sample Application enableDynamicPolicy Table 4 11 Sub elements of SecurityConfiguration Sub elements of Security Configuration Description Indicates that a timestamp must be sent in the outgoing mes Timestamp Sapes Indicates that a username token must be sent in the outgoing messages UsernameToken Indicates that a sign operation needs to be performed on the Sign outgoing messages Indicates that an encrypt operation needs to be performed on Encrypt the outgoing messages Indicates that a SAML assertion of subject confirmation type SAMLAssertion Sender Vouches SV must be sent in the security header of the outgoing messages Indicates that a timestamp must be present in the incoming messages RequireTimestamp
209. d Orga nization interface 29 getPostalAddresses method User interface 29 getPostalCode method PostalAd dress interface 29 getPrimaryContact method Orga nization interface 29 getRegistryObject method Que ryManager interface 10 22 getRegistryObjects method Que ryManager interface 10 22 getRootOrganization method Or ganization interface 32 getServiceBindings method Ser vice interface 31 getServices method Organiza tion interface 31 getSlots method RegistryObject interface 28 getSlotType method Slot inter face 28 getSpecificationLinks method ServiceBinding interface 31 getSpecificationObject method Speci ficationLink interface 31 getStateOrProvince method PostalAddress interface 29 getStreet method PostalAddress interface 29 getStreetNumber method Postal Address interface 29 getTelephoneNumbers method Or ganization interface or User inter face 29 INDEX getTimeStamp method Audit ableEvent interface 34 getType method EmailAddress in terface 30 getType method PostalAddress interface 29 getType method TelephoneNumber interface 29 getUr1 method TelephoneNumber interface 30 getUsageDescription method SpecificationLink interface 31 getUsageParameters method Speci ficationLink interface 31 getValues method Slot interface 28 getVersionInfo method Regis tryObjectImp1 class 35 getVersionName method Version InfoType interface 35 H help command lin
210. d an XML docu ment 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 xmlr xmlif createXMLStreamReader filename new Fi leInputStream filename when XMLStreamReader is created it is positioned at START_DOCUMENT event int eventType xmlr getEventType printEventType eventType printStartDocument xmlr check if there aremore eventsinthe input stream whi le xmir hasNextQ eventType xmlr next printEventType eventType these functionsprints the information about theparticular event by calling relevant function printStartElement xml1r printEndElement xmlr CURSORPARSE JAVA 113 printText xml1r printPIData Cxmlr printComment xm1r Note that next 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 represent
211. d differently depending on how the client applica tion is configured to process them However there are certain cases where a JAXB Provider indicates that it is no longer able to reliably detect and report errors In these cases the JAXB Provider will set the severity of the Valida tionEvent to FATAL_ERROR to indicate that the unmarshal validate or marshal operations should be terminated The default event handler and Validation EventCol lector utility class must terminate processing after being notified of a fatal error Client applications that supply their own ValidationEventHandler should also terminate processing after being notified of a fatal error If not unex pected behavior may occur XML Schemas Because XML schemas are such an important component of the JAXB process ing model and because other data binding facilities like JAXP work with DTDs instead of schemas it is useful to review here some basics about what XML schemas are and how they work XML Schemas are a powerful way to describe allowable elements attributes entities and relationships in an XML document A more robust alternative to DTDs the purpose of an XML schema is to define classes of XML documents that must adhere to a particular set of structural and data constraints that is you may want to define separate schemas for chapter oriented books for an online purchase order system or for a personnel database In the context of JAXB an XML document contai
212. d whether or not they have other associations Options d Removes the association between the current RegistryPackage and the specified RegistryPackage Removes the specified RegistryPackage only if its only remaining associations are to its member objects Member objects of the now removed RegistryPackage that are not anchored by being the target of other HasMember associations are now accessible as members of the root of the Registry Removes the specified RegistryPackage object and all its descendant objects except when an object has other associations Operands pattern A pattern comprising literal characters and the special characters asterisk representing zero or more characters and question mark repre senting one and only one character You can specify more than one pattern URN A URN starting with urn for example urn uuid 4a6741e7 4bel 4cfb 960a e5520356c4fd You can specify more than one URN SELECT 97 Examples The following command removes all RegistryPackage objects containing the string stat and all their descendants admin gt rm r stat select Executes an SQL select statement Synopsis select SQL Descnption The select command selects and lists the objects specified by evaluating the entire command as an SQL query If no argument is specified the command lists any objects selected by a preceding select command Operand SQL An SQL select statement without the lea
213. ddress 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 getState Q 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 void 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 43 Basic Examples This section describes five basic examples Unmarshal Read Modify Marshal Create Marshal Unmarshal Validate Validate On Demand that demonstrate how to Unmarshal an XML document into a Java content tree and access the data contained within it Modify a Java content tree Use the ObjectFactory class to create a Java content tree from scratch and then marshal it to XML data Perform validation during unmarshalling Validate a Java content tree at runtime Unmarshal Read Example The purpose of the Unmarshal Read exa
214. ddress to an Organization or User 299 Adding a User to an Organization 299 Adding a Child Organization to an Organization 300 Adding a Service Binding to a Service 301 Adding a Specification Link to a Service Binding 301 Adding a Child Concept to a Classification Scheme or Concept 302 Changing the State of Objects 302 Removing Objects 303 vii viii Chapter 8 CONTENTS Creating Relationships Between Objects 303 Developing Clients forthe Service Registy 1 Overview of JAXR About Registries and Repositories About JAXR JAXR Architecture About the Examples Setting Up a JAXR Client Starting the Registry Getting Access to the Registry Establishing a Connection to the Registry Obtaining and Using a RegistryService Object Querying a Registry Basic Query Methods JAXR Information Model Interfaces Finding Objects by Name Finding Objects by Type Finding Objects by Classification Finding Objects by External Identifier Finding Objects by External Link Finding Objects by Unique Identifier Finding Objects You Published Retrieving Information About an Object Using Declarative Queries Using Iterative Queries Invoking Stored Queries Querying a Registry Federation Publishing Objects to the Registry Creating Objects Saving Objects in the Registry Managing Objects in the Registry Creating Relationships Between Objects Associations Storing Items in the Repository Organizing Objects Within Registry Packages Changing the State of O
215. ddresses method and extract the Collection values as follows pc is the primary con tact Collection pcpAddrs pc getPostalAddresses Iterator pcaddIter pcpAddrs iteratorQ while pcaddIter hasNext Q PostalAddress pAd PostalAddress pcaddIter nextQ retrieve attributes To retrieve the telephone numbers for either an organization or a user call the getTelephoneNumbers method In the following code fragment org is the orga nization The code retrieves the country code area code main number and type of the telephone number Collection orgphNums org getTelephoneNumbers nul1 Iterator orgphIter orgphNums iterator while CorgphIter hasNext TelephoneNumber num TelephoneNumber orgphIter nextQ System out printInC Phone number num getCountryCode Q C num getAreaCode num getNumber num getTypeQ 30 DEVELOPING CLIENTS FOR THE SERVICE REGISTRY A TelephoneNumber can also have an extension retrievable through the getEx tension method If the number can be dialed electronically it can have a url attribute retrievable through the getUr1 method To retrieve the name of a user call the User getPersonName method A Per sonName has three attributes that correspond to the given name middle name s and surname of a user In the following code fragment pc is the primary contact PersonName pcName pc getPersonName System out printIn Co
216. 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 SCHEMA DERIVED JAXB CLASSES 35 Table 2 4 Schema to Java Bindings for the Basic Examples Continued XML Schema JAXB Binding lt xsd complexType 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 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 sShipDate 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 gt 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 Schema Denved J AXB Classes The code for the individual cla
217. default port Edit the following properties to specify the properties required for logging in to the Registry security keystorePath security storepass ebxmIrr security alias security keypass The security keystorePath property specifies the location of the key store file The security storepass property has a default setting of ebxmIrr The security alias and security keypass properties are the alias and password you specify when you use the User Registration Wizard of the Java UI See Getting Access to the Registry page 7 for details Feel free to change any of the data in the remainder of the file as you exper iment with the examples The Ant targets that run the client examples always use the latest version of the file SETTING UP A JAXR CLIENT Setting Up a J AXR Client This section describes the first steps to follow to implement a JAXR client that can perform queries and updates to the Service Registry A JAXR client is a cli ent program that can access registries using the JAXR API This section covers the following topics e Starting the Registry e Getting Access to the Registry e Establishing a Connection to the Registry e Obtaining and Using a RegistryService Object Starting the Registry To start the Registry you start the container into which you installed the Regis try Tomcat or the Sun Java System Application Server Getting Access to the Registry Any user of a JAXR client can perform
218. dentifier 22 finding objects you pub lished 23 introduction 5 iterative queries 38 publishing a service 63 retrieving organization and INDEX 125 user attributes 30 retrieving organization hi erarchies 53 stored queries 39 location xiv required software xiv exception property displaying value 99 exceptions displaying 74 executeQuery method Declara tiveQueryManager interface 35 executeQuery method Declara tiveQueryManagerImp class 36 exiting the Admin Tool 94 Explore menu 293 external classification schemes definition 49 external identifiers adding to registry objects 296 external links adding to registry objects 296 ExternalIdentifier interface 12 adding objects 49 retrieving objects 26 using to find objects 20 ExternalLink interface 12 adding objects 50 retrieving objects 27 using to find objects 21 extramural associations definition 59 ExtrinsicObject interface 12 creating objects 60 deleting objects 67 using objects as specification links 62 126 INDEX F federations registry querying 39 file system local base directory 72 changing current directory 92 files and folders copying to Registry 88 FindAl1MyObjects stored query 38 findClassificationSchemeByName method BusinessQueryManager interface 17 47 findObjects method Busi nessQueryManagerImp1 class 10 14 framework XWS Security 128 G getAccessURI method Service Binding interface 31 getAddress method Emai1Address i
219. deploy and run the examples you need a copy of the Application Server and the Java 2 Soft ware Development Kit Standard Edition J2SE SDK 1 4 2 or higher J2SE 5 0 is recommended The Application Server and J2SE SDK are contained in the J2EE 1 4 SDK If you already have a copy of the J2SE SDK you can download the Application Server from http java sun com j2ee 1 4 download html sdk You can also download the J2EE 1 4 SDK which contains the Application Server and the J2SE SDK from the same site Building the Examples Most of the examples in the Java WSDP 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 pro vided in each chapter Most of the tutorial examples in the J2EE 1 4 Tutorial 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 ABOUT THIS TUTORIAL XV contains additional tasks that invoke the Application Server administration util ity asadmin Directions for building the examples are provided in each chapter In order to run the Ant scripts you must configure your environment and proper ties files as follows e Add the bin directory of your J2SE SDK installation to the front of your path
220. der 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 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 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 72 USING JAXB Note When a lt class gt customization is specified in the appinfo element of a com plexType definition as it is here
221. des a description of its attributes Table 4 19 Attributes of RequireUsernameToken Attributes of RequireUsernameToken Description The identifier for the UsernameToken Indicates whether the username tokens in the incoming mes passwordDigestRe sages are required to contain the passwords in digest form or quired not Default value is true See also digestPassword attribute on lt UsernameToken gt Indicates whether a nonce is required to be present in the user nonceRequi red name tokens in the incoming messages Default value is true See also useNonce attribute on lt UsernameToken gt The maximum number of seconds the sending clock can devi exe lockSkew ate from the receiving clock Default is 60 timestampFreshness The maximum number of seconds the time stamp remains Limit valid Default is 300 The maximum number of seconds the nonce is cached by the maxNonceAge server for detecting a nonce replay Default is 900 RequireSignature The lt RequireSignature gt element is specified when a digital signature is required for all specified targets If no signature is present an exception is thrown In this release the only sub elements of RequireSignature that are ver ified while validating an incoming message are Target and SignatureTarget SEMANTICS OF SECURITY CONFIGURATION FILE ELEMENTS 157 Table 4 20 provides a description of its attributes Table 4 21 provides a description of its sub el
222. ding select because that is already present as the name of the command Examples The following command lists all ClassificationScheme objects in the Regis try admin gt select s from ClassificationScheme s set Sets a property value 98 ADMINISTERING THE SERVICE REGISTRY Synopsis set property value Desc nption The set command sets the value of a property of the Admin Tool shell The tool supports the following properties and values set debug true on yes false off no Enables or disables output of debugging messages set editor string Sets the command to use when the Admin Tool launches an interactive editor The default value is bin vi on UNIX and Linux systems and is notepad exe on Windows systems set verbose true on yes false off no Enables or disables output of more verbose messages when executing commands Operands property One of the following properties debug editor verbose value A supported value of the specified property See the Description section for details SHOW 99 Examples The following command sets the editor to usr bin vi instead of the default bin vi admin gt set editor usr bin vi show Displays a property value Synopsis show property Descnption The show command displays the value of a property of the Admin Tool shell If no argument is specified the command displays the values of all properties The command supports the followin
223. during marshalling to convert a value of the tar get type into a lexical representation 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 javaType 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 65 66 USING JAXB 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 p
224. dynamic policy sample application demonstrates how to specify or change the request and or response security policy at runtime using the XWS Security APIs Another sample that demonstrates using the XWS Security APIs is api sample which is discussed in XWS Security APIs Sample Application You would want to dynamically set the security policy for an application at runt ime when one of these conditions is present e Response policy When you don t know who the requester may be you want to be able to specify the response security policy after you determine the identity of the requester e Request policy When you don t know what the runtime parameters will be you want to discover these parameters such as whether SSL is enabled at the transport layer before you specify your request policy 256 UNDERSTANDING AND RUNNING THE XWS SECURITY SAMPLE APPLICATIONS The application prints out both the client and server request and response SOAP messages The output from the server may be viewed in the appropriate con tainer s log file The output from the client is sent to stdout or to whichever stream is used by the configured log handler Messages are logged at the INFO level In this example server side code is found in the dynamic policy server src sample directory Client side code is found in the dynamic policy cli ent src sample directory The asant or ant targets build objects under the build server and build client di
225. e Synopsis pwd Description The pwd command displays the path or paths to the current RegistryPackage using the best matching names for the current locale Also displays the locale for the path Example admin gt pwd en_US registry userData quit Exits the Admin Tool RM Synopsis quit Description The quit command exits the Admin Tool Example admin gt quit m Removes objects from a RegistryPackage Synopsis rm d r pattern URN Description The rm command removes the member objects of the current RegistryPackage whose names in the current locale match the patterns specified by a pattern or URN When a matching RegistryObject is a member of multiple RegistryPackage objects this command removes only the association between the current Regis tryPackage and the object The object is removed from the Registry only when the removal of the association leaves the object with no association with any other RegistryObject When a matching member object is itself a RegistryPackage that contains other objects neither the object nor the association between the current Registry Package and the member RegistryPackage is removed unless either the r or the d option is specified 95 96 ADMINISTERING THE SERVICE REGISTRY When both the d and r options are specified the d option is applied recur sively so all objects that would be selected by r and their associations are remove
226. e id_T use optional gt lt xs attribute name strId type id_T use optional gt lt xs attribute name keylIdentifier type id_T use optional gt 112 A XWS SECURITY FORMAL SCHEMA DEFINITION lt xs attribute name encodingType use prohibited gt lt xs attribute name keyReferenceType use optional default Identifier gt lt xs simpleType gt lt xs restriction base xs string gt lt xs enumeration value Identifier gt lt xs enumeration value Embedded gt lt xs restriction gt lt xs simpleType gt lt xs attribute gt lt xs attribute name type use required gt lt xs simpleType gt lt xs restriction base xs string gt lt xs enumeration value HOK gt lt xs enumeration value SV gt lt xs restriction gt lt xs simpleType gt lt xs attribute gt lt xs complexType gt lt xs complexType name RequireSAMLAssertion_T gt lt xs attribute name id type id_T use optional gt lt xs attribute name authorityId type id_T use optional gt lt xs attribute name strId type id_T use optional gt lt xs attribute name type type xs string use required fixed SV gt lt xs attribute name encodingType use prohibited gt lt xs attribute name keyReferenceType use optional default Identifier gt lt xs simpleType gt lt xs restriction base xs string gt lt xs enumeration value Direct gt lt xs enumeration value Identifier gt lt xs enumeration v
227. e Application Server a From a Unix machine enter the following command from a terminal window asadmin start domain domain1 FURTHER INFORMATION 263 b From a Windows machine choose Start Programs Sun Microsystems J2EE 1 4 Start Default Server 3 Build and run the application from a terminal window or command prompt e On the Application Server the command to build and run the applica tion is asant run sample e On the other containers the command to build and run the application is ant run sample Note To run the sample against a remote server containing the deployed endpoint use the run remote samp e target in place of the run samp1e target In this situa tion make sure that the endpoint host endpoint port http proxyHost http proxyPort and service url properties are set correctly in the build prop erties file as discussed in Setting Build Properties before running the sample If the application runs successfully you will see a message similar to the follow ing echo Running the client program java Sending Message Start java Sending Message End java Received Message Start java Received Message End You can view similar messages in the server logs lt SJSAS_HOME gt domains lt domain name gt logs server log lt TOMCAT_HOME gt logs launcher server log lt SJISWS_HOME gt lt Virtual Server Dir gt logs errors Further Information
228. e URL that can dial this number electronically telephone3 type The type of the third TelephoneNumber If a third TelephoneNumber is specified the type is required it must be specified either on the command line or in a properties file It can have any of the following values Beeper FAX HomePhone Mobi 1lePhone or OF ficePhone telephone3 areaCode The area code of the third Tel ephoneNumber telephone3 countryCode The country code of the third TelephoneNumber telephone3 extension ADD USER 85 The extension of the third Tel ephoneNumber telephone3 number The telephone number suffix not including the country or area code of the third TelephoneNumber If a third TelephoneNumber is specified the number is required it must be specified either on the command line or in a properties file telephone3 URL The URL of the third TelephoneNumber the URL that can dial this num ber electronically emailType emaill type The type of the first EmailAddress The type is required it must be spec ified either on the command line or in a properties file It can have either of the following values HomeEmail or Of fi ceEmai1 emailAddress email emaill address The first email address The first email address is required email2 type The type of the second EmailAddress If a second Emai 1Address is spec ified the type is required it must be specified either on the command line or in a properties file It
229. e and or RequireEncryption ele ment but we have not done this yet The swa server xm file looks like this lt xwss JAXRPCSecurity xmIns xwss http java sun com xml ns xwss config gt lt xwss Service gt lt Port 1 SwA Scenario 1 Sign Attachment Only gt lt xwss Port name http xmlsoap org Ping Pingl gt lt xwss SecurityConfiguration dumpMessages true gt RUNNING THE SWA SAMPLE APPLICATION 247 lt xwss SecurityConfiguration gt lt xwss Port gt lt Port 2 SwA Scenario 2 Encrypt Attachment Only gt lt xwss Port name http xmlsoap org Ping Ping2 gt lt xwss SecurityConfiguration dumpMessages true gt lt xwss SecurityConfiguration gt lt xwss Port gt lt Port 3 SwA Scenario 3 Attachment Signature and Encryp tion gt lt xwss Port name http xmlsoap org Ping Ping3 gt lt xwss SecurityConfiguration dumpMessages true gt lt xwss Port gt lt Port 4 SwA Scenario 4 Attachment Signature and Encryp tion With MIME Headers gt lt xwss Port name http xmlsoap org Ping Ping4 gt lt xwss SecurityConfiguration dumpMessages true gt lt xwss Port gt lt xwss Service gt lt xwss SecurityEnvironmentHand1ler gt com sun xml wss sample SecurityEnvironmentHandler lt xwss SecurityEnvi ronmentHandler gt lt xwss JAXRPCSecurity gt Running the SwA Sample Application To run the swainterop sample application follow these steps 1 Complete the
230. e gt client src lt sample_name gt directory The asant or ant targets build objects under the build server and build client directo ries These examples can be deployed onto any of the following containers For the purposes of this tutorial only deployment to the Sun Java System Application Server Platform Edition 8 1 will be discussed The README txt file for each example provides more information on deploying to the other containers The following containers can be downloaded from http java sun com webservices contain ers index html e Sun Java System Application Server Platform Edition 8 1 Application Server e Sun Java System Web Server 6 1 Web Server If you are using the Java SDK version 5 0 or higher download service pack 4 for the Web Server If you are using version 1 4 2 of the Java SDK download service pack 2 or 3 e Tomcat 5 Container for Java WSDP Tomcat These examples use keystore and truststore files that are included in the lt JWSDP_HOME gt xws security etc directory For more information on using 175 176 INTRODUCTION TO XML AND WEB SERVICES SECURITY keystore and truststore files read the keytool documentation at http java sun com j2se 1 5 0 docs tooldocs solaris keytool html Refer to the application s README txt file if deploying on the Web Server or Tomcat The following list provides the name a short description and a link to further discussion of each of the sample applications a
231. e of the code attribute for its Clas sificationNodes NotificationOption Type Defines the different ways in which a client may wish to be notified by the registry of an event within a Subscription ObjectType Defines the different types of RegistryObjects a registry may support PhoneType Defines the types of telephone numbers QueryLanguage Defines the query languages supported by a registry FINDING OBJECTS BY CLASSIFICATION Table 8 4 Canonical Classification Schemes Continued ResponseStatusType Defines the different types of status for a RegistryResponse StatusType Defines the different types of status for a RegistryObject Defines the groups that a User may belong to for access con SubjectGroup tol purposes Defines the roles that may be assigned to a User for access control purposes SubjectRole For a sample program that displays all the canonical classification schemes and their concepts see lt INSTALL gt registry samples classification schemes src JAXRGetCanonicalSchemes java To run this example follow these steps 1 Go to the directory lt INSTALL gt registry samples classification schemes 2 Type the following command ant get schemes Finding Objects by Classification Examples For examples of finding objects by classification see the two examples in lt INSTALL gt registry samples query classification src JAXRQueryBy Classification java and JAXRQuer
232. e option 72 help command 91 I information model JAXR 2 3 interfaces 11 interactive mode 71 internal classification schemes definition 47 International String interface 13 interoperability secure 133 intramural associations definition 59 127 128 INDEX InvocationModel classification scheme 18 IterativeQueryParams class 37 J jaas sample application 226 Java Cryptography Architecture JCA 133 Java Cryptography Extension JCE 133 Java KeyStore JKS 197 javax xml registry package 3 javax xml registry infomodel package 3 javax xml registry 1lifeCycleM anagerURL connection property 9 javax xml registry queryMan agerURL connection property 9 JAXR 1 architecture 3 classification schemes 17 clients 3 7 creating connections 8 creating objects 42 definition 2 information model 2 11 overview provider 3 publishing objects to a registry 4 querying a registry 10 specification 2 JAXRExamples properties file JAXR examples 6 JAX RPC securing applications 128 JAX RPC applications securing 128 JAXRPCSecurity element 136 JAXRUti lity class getConnectionFactory method 8 JCE JCA 132 JCE provider configuring 207 JSR 105 132 JSR 106 132 K Key interface 13 using to find objects 22 keyexport command 128 199 keypass command line option 72 keystore files for XWS Security samples 209 L languages changing default 284 1cd command 92 LifeCycleManager interface 4 9 localdir
233. e remainder of this appendix lists the contents of these JAR files Refer to Chapter 3 Streaming API for XML for detailed information about StAX and Sun s SJSXP implementation sjsxp jar The sjsxp jar file contains the following files META INF services javax xm stream XMLEventFactory META INF services javax xml stream XMLInputFactory META INF services javax xml stream XMLOutputFactory META INF pack properties com sun xm1 stream xerces imp1 msg DOMMessages properties com sun xml stream xerces imp1 msg XMLMessages properties com sun xml stream xerces imp1 msg XMLSchemaMessages propertie s com sun xml stream xerces impl msg XMLSerializerMessages prope rties com sun xml stream BufferManager class com sun xml stream Constants class 115 116 SJSXP JAR FILES com sun xm1 stream Constants ArrayEnumeration class com sun xm1 stream Entity class com sun xm1 stream Entity ExternalEntity class com sun xm1 stream Entity InternalEntity class com sun xm1 stream Entity ScannedEntity class com sun xm1 stream EventFilterSupport class com sun xml stream Fi leBufferManager class com sun xml stream PropertyManager class com sun xml stream StaxEntityResolverWrapper class com sun xm1 stream StaxErrorReporter class com sun xm1 stream StaxErrorReporter 1 class com sun xml1 stream StaxXMLInputSource class com sun xml stream StreamBufferManager class com sun xml stream StreamBufferManager RewindableInputStream c lass com sun xml stream XMLBuffe
234. e searched The BusinessQueryManagerImp1 findObjects method takes a collection of FindQualifier objects as its second argument and takes a collection of name patterns as its third argument Its method signature is as follows public BulkResponse findObjects java lang String objectType java util Collection findQualifiers java util Collection namePatterns java util Collection classifications java util Collection specifications java util Collection externalidentifiers java util Collection externalLinks throws JAXRException You can use wildcards in a name pattern Use percent signs to specify that the query string occurs at the beginning end or middle of the object name FINDING OBJECTS BY NAME For example the following code fragment finds all the organizations in the Reg istry whose names begin with a specified string qString and sorts them in alphabetical order Define find qualifiers and name patterns Collection findQualifiers new ArrayListQ findQualifiers add FindQualifier SORT_BY_NAME_ASC Collection namePatterns new ArrayListQ namePatterns add qString Find organizations with name that starts with qString BulkResponse response bqm findObjectsC Organization findQualifiers namePatterns null null null null Collection orgs response getCollection The findObjects method is not case sensitive unless you specify FindQuali fier CASE_SENSITIVE_MATCH In the previous fragment the fir
235. eci fied in the WSS Username Token Profile Accordingly there are two Request classes with which the PasswordValidation Callback can be initialized Note A validator for WSS Digested Username Pass word is provided as part of this callback with classname PasswordValidation Callback DigestPass wordValidator This class implements WSS digest password validation The method for computing password digest is described in http docs oasis open org wss 2004 01 o0asis 200401 wss user name token profi le 1 0 pdf For more information see the ServerSecurityEnviron mentHand ler in lt JWSDP_HOME gt xws secu rity samples jaas sam ple src com sun xml1 wss samp le Request Inner Classes Defined 1 PlainTextPass wordRequest Rep resents a validation request when the pass word in the username token is in plain text 2 DigestPasswor dRequest Repre sents a validation request when the pass word in the username token is in digested form Methods in the Request Classes The following methods are present in the PlainText PasswordRequest public String getUser name public String getPass word The following methods are present in the DigestPass wordRequest public void setPass word String password This method must be invoked by the Call backHandler while handling a Callback initialized with DigestPasswor dRequest to set the plain text password on the Callback public java l
236. ed when the client side security configuration is SIMPLE SAMPLE SECURITY CONFIGURATION FILES 219 either encrypt using symmkey client xml or encrypt client xm1 The dif ference in the two client configurations is the key material used for encryption The encrypt using symmkey client xml1 file looks like this lt xwss JAXRPCSecurity xmIns xwss http java sun com xml ns xwss config gt lt xwss Service gt lt xwss SecurityConfiguration dumpMessages true gt lt Encrypt using a symmetric key associated with the given alias gt lt xwss Encrypt gt lt xwss SymmetricKey keyAlias Sessionkey gt lt xwss Encrypt gt lt xwss SecurityConfiguration gt lt xwss Service gt lt xwss SecurityEnvironmentHand1ler gt sample SecurityEnvironmentHandler lt xwss SecurityEnvi ronmentHand1er gt lt xwss JAXRPCSecurity gt Adding a Usemame Password Token The security configuration pair user pass authenticate client xml and user pass authenticate server xml enable the following tasks Client adds a username password token and sends a request Server authenticates the username and password against a username pass word database Server sends response The user pass authenticate client xml file looks like this lt xwss JAXRPCSecurity xmlIns xwss http java sun com xml ns xwss config gt lt xwss Service gt lt xwss SecurityConfiguration dumpMessages true gt lt Default
237. ed to the signed algorithm object The default value is http www w3 org 2000 09 xm1dsig shal DataEncryptionMethod The lt DataEncryptionMethod gt element specifies the encryption algorithm to be applied to the cipher data The recommendation that discusses this method is the W3C XML Encryption Syntax and Processing recommendation which can be 169 170 INTRODUCTION TO XML AND WEB SERVICES SECURITY viewed at http www w3 org TR 2002 REC xmlenc core 20021210 sec EncryptionMethod The attributes of lt DataEncryptionMethod gt are discussed in Table 4 39 Table 4 39 Attributes of DataEncryptionMethod Attributes of DataEncryptionMethod Description The algorithm to be used for encrypting data The default value is http www w3 org 2001 04 xmlenc aes128 cbc Other options include http www w3 org 2001 04 xmlenc aes256 cbc and http www w3 org 2001 04 xmlenc tripledes cbc algorithm Note Although the schema indicates that http www w3 org 2001 04 xmlenc aes128 cbc is the default algorithm for lt DataEncryptionMethod gt for backward compatibility this implementation still uses http ww w3 org 2001 04 xmlenc tripledes cbc as the default How Do I SPECIFY THE SECURITY CONFIGURATION FOR THE BUILD FILES KeyEncryptonMethod The lt KeyEncryptionMethod gt element specifies the public key encryption algo rithm to be used for encrypting and decrypting keys Its attributes are discussed in
238. efault value is true Note that a true value for this attribute makes sure that a timestamp will be sent in the outgoing messages even if the lt Timestamp gt element has not includeTimestamp been specified Also note that at most one timestamp is sent in a message When includeTimestamp is true a Timestamp element with the default value is added and is signed i e Timestamp is added as one of the targets in the corresponding signature element 152 INTRODUCTION TO XML AND WEB SERVICES SECURITY Table 4 15 Sub elements of Sign Indicates the certificate corresponding to the private key used for signing If this element is not present attempt is made to X509Token get the default certificate from the security environment han dler Only one of the X509Token SAMLAssertion and Sym metricKey elements may be present at a time Indicates the certificate corresponding to the SAML assertion SAMLAssertion used for signing Only one of the X5 9Token SAMLAsser tion and SymmetricKey elements may be present at a time Indicates the symmetric key corresponding to the private key used for signing Only one of the X5 9Token SAMLAsser SymmetricKey tion and SymmetricKey elements may be present at a time SymmetricKey signatures are not supported for signatures in this release Indicates the canonicalization algorithm applied to the CanonicalizationMethod lt SignedInfo gt element prior to performing signature calcu lations
239. eld To search by classification follow these steps 1 Expand the root node to view the full list of classification schemes The number in parentheses after each entry indicates how many concepts the parent contains 2 Expand the node for the classification scheme you want to use VIEWING SEARCH RESULTS 3 Expand concept nodes beneath the classification scheme until you find the leaf node a node with no concepts beneath it by which you want to search 4 Select the leaf node 5 Optionally restrict the search by choosing an object type or specifying a name or description string 6 Click the Search button Viewing Search Results Objects found by a search appear in the Registry Objects area The Registry Objects area consists of the following e Buttons labeled Save Approve Deprecate Undeprecate Relate and Delete which allow you to perform actions on objects You must be the object s creator to perform any of these actions e A found objects display consisting of a search results table with the follow ing columns Pick checkbox Select any two objects to activate the Relate button See Creating Relationships Between Objects page 303 for details Details link Click this link to open the Details area directly below the Registry Objects area see Viewing Object Details Object Type field Name field Description field Version field VersionComment field Pin checkbox Select this checkbo
240. ements Table 4 20 Attributes of RequireSignature Attributes of RequireSignature Description The id to be set on the signature of the message to be sent This is also useful in referring to the signature from other places in the security configuration file Indicates whether a timestamp must be included in the signa requireTimestamp tures in the incoming messages Default value is true See also includeTimestamp attribute on lt Sign gt Table 4 21 Sub elements of RequireSignature Sub elements of RequireSignature Description Indicates the certificate corresponding to the private key used for signing If this element is not present attempt is made to X509Token get the default certificate from the security environment han dler Only one of the X509Token SAMLAssertion and Sym metricKey elements may be present at a time Indicates the certificate corresponding to the SAML assertion SAMLAssertion used for signing Only one of the X5 9Token SAMLAsser tion and SymmetricKey elements may be present at a time Indicates the symmetric key corresponding to the private key SymmetricKey used for signing Only one of the X5 9Token SAMLAsser tion and SymmetricKey elements may be present at a time Indicates the canonicalization algorithm applied to the CanonicalizationMethod lt SignedInfo gt element prior to performing signature calcu lations Indicates the algorithm used for signature generation and vali
241. en Description Indicates the certificate to be used for encryption If this ele ment is not present attempt is made to get the default certifi cate from the security environment handler This element must not be specified if the lt SymmetricKey gt or lt SAMLAssertion gt sub element of lt Encrypt gt is specified SymmetricKey Indicates the symmetric key to be used for encryption This element must not be specified if the lt X509Token gt or lt SAM LAssertion gt sub element of lt Encrypt gt is present SAMLAssertion Indicates the SAML assertion to be used for encryption This element must not be specified if the lt X509Token gt or lt Sym metricKey gt sub element of lt Encrypt gt is present KeyEncryptionMethod Specifies the public key encryption algorithm to be used for encrypting and decrypting keys DataEncryptionMethod Specifies the encryption algorithm to be applied to the cipher data Target Identifies the resource that needs to be encrypted The Target element has been deprecated and is provided only for back ward compatibility EncryptionTarget Identifies the resource that needs to be encrypted 153 154 INTRODUCTION TO XML AND WEB SERVICES SECURITY SAMLAssertion The lt SAMLAssertion gt element is used to define the SAML assertion to be trans ferred from identity providers to service providers These assertions include statements that service providers use to
242. ences 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 means 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 101 102 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 xml 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 yo
243. entation 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 X509Certificate 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 278 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 getAlgori
244. ents Table 1 1 Core Components in a JAXB Implementation XML Schema An XML schema uses XML syntax to describe the relationships among elements attributes and entities in an XML document The purpose of an XML schema is to define a class of XML documents that must adhere to a particular set of structural rules and data constraints For example you may want to define separate schemas for chapter oriented books for an online purchase order system or for a personnel database In the context of JAXB an XML document containing data that is constrained by an XML schema is referred to as a document instance and the structure and data within a document instance is referred to as a content tree Binding By default the JAXB binding compiler binds Java classes and packages Customizations to a source XML schema based on rules defined in Section 5 Binding XML Schema to Java Representations in the JAXB Specification In most cases the default binding rules are sufficient to generate a robust set of schema derived classes from a wide range of schemas There may be times however when the default binding rules are not sufficient for your needs JAXB supports customizations and overrides to the default binding rules by means of binding customizations made either inline as annotations in a source schema or as statements in an external binding customization file that is passed to the JAXB binding compiler Note that custom JAXB binding customizati
245. ep process 1 Create the object 2 Save the object The object does not appear in the Registry until after you save it At this release ignore the Create User Account menu item You can publish objects to the registry without performing any authentication steps To create and save a new registry object follow these steps 1 In the menu area click Create a New Registry Object ADDING A CLASSIFICATION TO AN OBJECT 2 In the Registry Objects area choose an object type from the drop down list and click Add 3 A Details form for the object appears in the Details area 4 Type a name and description in the fields of the Details form Type values for other fields that appear in the Details form 5 Click Save to save the object A status message appears indicating whether the save was successful Either before or after you save the object you can edit it by adding other objects to it Table 7 4 lists the objects you can add The following sections describe how to add these objects Adding a Classification to an Object To create a classification you use an internal classification scheme An internal classification scheme contains a set of concepts whose values are known to the Registry To add a Classification to an object search for the appropriate classification scheme then choose a concept within that classification scheme Follow these steps 1 In the Details area for the object click the Classifications butt
246. epts You can create your own classification schemes and concept hierarchies for clas sifying registry objects To do so follow these steps 1 Use the LifeCycleManager createClassificationScheme method to create the classification scheme 45 46 DEVELOPING CLIENTS FOR THE SERVICE REGISTRY 2 Use the LifeCycleManager createConcept method to create concepts 3 Use the ClassificationScheme addChildConcept method to add the concepts to the classification scheme 4 For a deeper hierarchy use the Concept addChi 1dConcept method to add child concepts to the concepts 5 Save the classification scheme The LifeCycleManager createClassificationScheme method has several forms You can specify two arguments a name and description as either String or InternationalString values For example to create a classification scheme to describe how books are shelved in a library you could use the following code fragment ClassificationScheme cs blcm createClassificationScheme LibraryFloors Scheme for Shelving Books An alternate form of the createClassificationScheme method takes one argu ment a Concept and converts it to a ClassificationScheme The createConcept method takes three arguments a parent a name and a value The parent can be either a Classi ficationScheme or another Concept It is acceptable to specify a value but no name The following code fragment uses a static String array containing the names of the fl
247. er CextScheme Sun SUNW object addExternalidentifier CextId The example lt INSTALL gt registry samples publish object src JAXRPub lishObject java described in Adding Classifications Example page 48 also adds an external identifier to an object 49 50 DEVELOPING CLIENTS FOR THE SERVICE REGISTRY Adding Extemal Links to Objects To add an external link to an object you call the LifeCycl eManager createEx ternalLink method which takes two arguments the URI of the link and a description of the link Then you add the external link to the object String eiURI http java sun com String eiDescription Java Technology ExternalLink extLink blcm createExternalLink eiURI eiDescription object addExternalLink CextLink The URI must be a valid URI and the JAXR provider checks its validity If the link you specify is outside your firewall you need to specify the system proper ties http proxyHost and http proxyPort when you run the program so that JAXR can determine the validity of the URI To disable URI validation for example if you want to specify a link that is not currently active call the ExternalLink setValidateURI method before you create the link extLink setValidateURI false The example lt INSTALL gt registry samples publish object src JAXRPub lishObject java described in Adding Classifications Example page 48 also adds an external link to an object Adding Slots to Ob
248. er 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 y public ObjectFactory super new primer po ObjectFactory GrammarInfolImp Create an instance of the specified Java content interface public Object newInstance Class javaContentInterface throws javax xml bind JAXBException Get the specified property This method can only be used to get provider specific properties Attempting to get an undefined property will result jn a PropertyException being thrown public Object getProperty String name throws javax xml bind PropertyException return super newInstance javaContentInterface Set the specified property This method can only be used to set provider specific properties Attempting to set an undefined property will result jn a PropertyException being thrown public void setProperty String name Object value throws javax xml bind PropertyException return super getProperty name super setProperty name value SCHEMA DERIVED JAXB CLASSES 39 Create an instance of PurchaseOrder 3 public primer po PurchaseOrder createPurchaseOrder throws javax xml bind JAXBException return primer po PurchaseOrder newInstance primer po PurchaseOrder class
249. er 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 event information as an XMLEvent object even when using the cursor API Instantiating an XMLEventAlloc ator The first step is to create a new XMLInputFactory and instantiate an XMLEven tAllocator 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 EVENTPARSE JAVA 115 Creating an Event Iterator The next step is to create an event iterator int eventType xmlr getEventTypeQ whi leCxmIr hasNextQ eventType xmIr nextQ Get all Book elements as XMLEvent object ifCeventType XMLStreamConstants START_ELEMENT amp amp xmlr getLocalName equalsC Book get immutable XMLEvent StartElement event getXMLEvent xmlIr asStartElement System out printInC EVENT event toString Creating the Allocator Method The final step is to create the XMLEventAl locator method private static XMLEvent getXMLEvent XMLStreamReader reader throws XMLStreamException return allocat
250. erver and build client directories This example uses keystores and truststores which are included in the xws security etc directory For more information on using keystore and truststore files read the keytool documentation at the following URL http java sun com j2se 1 5 0 docs tooldocs solaris keytool html Plugging in Secunty Configurations This example makes it simple to plug in different client and server side configu rations describing security settings This example has support for digital signa tures XML encryption decryption and username token verification This example allows and demonstrates combinations of these basic security mecha nisms through configuration files See Simple Sample Security Configuration Files for further description of the security configuration options defined for the simple sample application To specify which security configuration option to use when the sample applica tion is run see Running the Simple Sample Application follow these steps 1 Open the build properties file for the example This file is located at lt JWSDP_HOME gt xws security samples simple build properties 2 To set the security configuration that you want to run for the client locate the client security config property and uncomment one of the client security configuration options The client configuration options are listed in Simple Sample Security Configuration Files and also list which client and server con
251. et gt lt RequireSignature id unique_policy_identifier requirelimestamp true false gt Key Bearing Token lt CanonicalizationMethod algorithm http www w3 org 2001 10 xml exc c14n others gt lt SignatureMethod algorithm C http www w3 org 2000 09 xmldsig rsa shal others gt lt Target gt of type Target and or SignatureTarget lt RequireSignature gt lt Transform algorithm supported algorithms gt lt AlgorithmParameter name name value value gt lt Transform gt lt RequireTimestamp id unique_policy_id maxClockSkew 60 timestampFreshnessLimit 300 gt lt RequireUsernameToken id unique_policy_id nonceRequired C true false passwordDigestRequired true false maxClockSkew 60 timestampFreshnessLimit 300 maxNonceAge 900 gt lt Requi reUsernameToken gt lt OptionalTargets gt lt Target gt SEMANTICS OF SECURITY CONFIGURATION FILE ELEMENTS 145 lt OptionalTargets gt lt Target type C qname uri xpath contentOnly C true false enforce C true false gt value lt Target gt Semantics of Security Configuration File Elements This section contains a discussion regarding the semantics of security configura tion file elements J AXRPC Security The lt JAXRPCSecurity gt element is the top level XML element for XWS Secu rity configuration files for applications that use JAX RPC The top level XML eleme
252. etrieve all objects you have published of a specified type where type_name is case sensitive ant get obj type Dtype type_name Note At this release every user has the identity RegistryOperator Because this user owns all the objects in the Registry the get obj target takes a long time to run and the get obj type target may take a long time if the type_name is one with many objects Classi ficationNode for example 23 24 DEVELOPING CLIENTS FOR THE SERVICE REGISTRY Retrieving Information About an Object Once you have retrieved the object or objects you are searching for you can also retrieve the object s attributes and other objects that belong to it its name description type ID values classifications external identifiers external links and slots For an organization you can also retrieve the primary contact a User object postal address telephone numbers and the services that the organization offers For a user you can retrieve the name email addresses postal address and telephone numbers For a service you can retrieve the service bindings For an object you can also retrieve the audit trail which contains the events that have changed the object s state and the version You can also retrieve an object s version number which is updated whenever a change is made to one of the object s attributes This section covers the following topics e Retrieving an organization hierarchy e Retrieving the
253. ew the objects 2 Expand the ClassificationSchemes node to open the Classification Schemes tree hierarchy in the menu area 3 Click any file icon to view that classification scheme in the Registry Objects area 4 Expand a classification scheme node to see the Concept folders beneath it Not all classification schemes have concepts that are viewable in the Explore menu The last seven classification schemes have concepts that are not viewable here 5 Click a Concept folder to view that concept in the Registry Objects area 293 294 USING THE SERVICE REGISTRY WEB CONSOLE To explore the userData folder follow these steps 1 Expand the userData node 2 Expand the RegistryObject node Do not click the folder unless you want to view all registry objects The node named folder1 has no content 3 Click a folder to view the registry objects of that type Expand a node to view the object types at the next level When you have finished click Hide Explorer to close the Explore menu and clear the results area Publishing and Managing Registry Objects e Publishing Objects e Adding a Classification to an Object e Adding an External Identifier to an Object e Adding an External Link to an Object e Adding Custom Information to an Object Using Slots e Changing the State of Objects e Removing Objects e Creating Relationships Between Objects Publishing Objects Publishing objects to the registry is a two st
254. example the parser filters out all events except StartElement and EndElement 120 STREAMING API FOR XML Implementing the Steamfilter Class The MyStreamFilter implements javax xml stream StreamFilter public class MyStreamFilter implements javax xml stream StreamFilter 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 newInstance 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 catch Exception ex ex printStackTrace System out println FACTORY xmlif System out printInC filename filename 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 1lteredReader xmlif createXMLStreamReader fis new MyStreamFilter int eventType xmIr getEventTypeQ printEventType eventType whi leCxmIr hasNext Q eventType xmIr nextQ printEventType eventType printName xm1r eventType MYSTREAMFILTER JAVA 121 printText xml1r if xmlr isStartEleme
255. f you specify the edit option the Admin Tool launches an editor so that you can edit the new user s information See the option description for details The properties files that you load with load or edit with edit use the ISO 8859 1 charset as do all Java properties files See the documentation for java util Properties load InputStream for details on how to represent other characters not in ISO 8859 1 in properties files 79 80 ADMINISTERING THE SERVICE REGISTRY Options edit Causes the Admin Tool to launch an editor so that you can edit the new user s information The tool launches the editor after evaluating the other command line parameters so editing starts with the result of evaluating any information specified on the command line or with a properties file The editing program must terminate without error before the command can continue At the time of this writing edit currently works with emacsclient and the NetBeans command bin runide sh open but not very well has not been shown to work with vi and has not been tested on Windows load Specifies a Java properties file whose contents specify properties for the user The property names are the same as those of the long form of the add user command options for example lastName and post1 type fn firstName Specifies the first name of a user In lastName Specifies the last name of a user A last name is required it must be spec ified either o
256. fication scheme use the program lt INSTALL gt registry samples classification schemes src JAXRQueryScheme java To run the example follow these steps 1 Go to the directory lt INSTALL gt registry samples classification schemes 2 Type the following command ant del scheme Dname LibraryFloors Adding Classifiations to Objects Objects can have one or more classifications based on one or more classification schemes taxonomies To establish a classification for an object the client first locates the taxonomy it wants to use The client then creates a classification using the classification scheme and a concept a taxonomy element within the classification scheme For information on creating a new classification scheme with a hierarchy of con cepts see Creating Relationships Between Objects Associations page 57 A classification scheme with a concept hierarchy is called an internal classification scheme To add a classification that uses an existing classification scheme you usually call the BusinessQueryManager findClassificationSchemeByName method This method takes two arguments a Collection of FindQualifier objects and 47 48 DEVELOPING CLIENTS FOR THE SERVICE REGISTRY a String that specifies a name pattern It is an error for this method to return more than one result so you must define the search very precisely For example the following code fragment searches for the classification scheme named Asso Cciat
257. figurationElements gt lt xs choice gt lt xs element name Timestamp type Timestamp_T minOccurs 0 gt lt xs element name RequireTimestamp type RequireTimestamp_T minOccurs 0 gt lt xs element name UsernameToken type UsernameToken_T minOccurs 0 gt lt xs element name RequireUsernameToken type RequireUsernameToken_T minOccurs 0 gt lt xs element name SAMLAssertion type SAMLAssertion_T minOccurs 0 gt lt xs element name RequireSAMLAssertion 106 A XWS SECURITY FORMAL SCHEMA DEFINITION type RequireSAMLAssertion_T minOccurs 0 gt lt xs element name OptionalTargets type OptionalTargets_T minOccurs 0 gt lt xs element name Sign type Sign_T gt lt xs element name Encrypt type Encrypt_T gt lt xs element name RequireSignature type RequireSignature_T gt lt xs element name RequireEncryption type RequireEncryption_T gt lt xs choice gt lt xs group gt lt xs complexType name Timestamp_T gt lt xs attribute name id type id_T use optional gt lt xs attribute name timeout type xs decimal use optional default 300 gt lt xs complexType gt lt xs complexType name RequireTimestamp_T gt lt xs attribute name id type id_T use optional gt lt xs attribute name maxClockSkew type xs decimal use optional default 60 gt lt xs attribute name timestampFreshnessLimit type xs decimal use optional default 300 gt lt xs c
258. figurations work together For example if you want to use XML Encryption for the client you would uncomment this option Client Security Config file client security config config encrypt client xm Be sure to uncomment only one client security configuration at a time SIMPLE SAMPLE SECURITY CONFIGURATION FILES 3 To set the security configuration that you want to run for the server locate the server security config property and uncomment one of the server security configuration options The server configuration options and which server options are valid for a given client configuration are listed in Simple Sample Security Configuration Files For example if you want to use XML Encryption for the server you would uncomment this option Server Security Config file server security config config encrypt server xm Be sure to uncomment only one client security configuration at a time 4 Save and exit the build properties file 5 Run the sample application as described in Running the Simple Sample Applica tion Simple Sample Security Configuration Files The configuration files available for this example are located in the xws secu rity samples simple config directory The configuration pairs available under this sample include configurations for both the client and server side Some possible combinations are discussed in more detail in the referenced sec tions Dumping the Request and or the Response The secu
259. for signing the object DigestMethod 166 INTRODUCTION TO XML AND WEB SERVICES SECURITY Table 4 32 Sub elements of SignatureTarget Continued Sub elements of SignatureTarget Description a ae Identifies the transform algorithm to be applied before signing the object EncryptionTarget The lt EncryptionTarget gt sub element identifies the type of encrypted structure being described If neither the lt EncryptionTarget gt nor lt Target gt sub ele ments are specified the default value is a target that points to the contents of the SOAP body of the message The target value is a string that specifies the object to be encrypted and which is specified between the lt EncryptionTar get gt target_value lt EncryptionTarget gt elements You can specify attachments as targets by setting the type attribute to uri and specifying the target value as cid lt part name gt which specifies the value of the Content ID CID header of the attachment When the Content ID is not know until runtime such as when auto generated CIDs are run under JAX RPC the attachment can be referenced by setting the type attribute to uri and specifying the target value as attachmentRef lt part name gt where part name is the WSDL part name of the AttachmentPart Auto generated CIDs in JAX RPC following the form lt partname gt lt UUID gt lt Domain gt The special value cid can be used to refer to all attachments of a SOAPMessage SEMANTICS OF
260. from the Type combo box HomeEmail or OfficeEmail Type a value in the Email Address field Click Add to close the Details Panel window The new version of the object appears in the Registry Objects area Click Save in the Details area for the object Adding a Userto an Organization An Organization can have one or more users One user is the primary contact which is normally the user that created the organization To create a new user and add it to an Organization follow these steps 1 In the Details area for the Organization click the Users tab 300 USING THE SERVICE REGISTRY WEB CONSOLE The Users table appears Click Add A Details Panel window opens In the Name field type the last name of the user to the left of the comma and optionally the first and middle names to the right of the comma 4 Optionally type a description of the user in the Description field Inthe First Name Middle Name and Last Name fields type the first name middle name and surname of the user All fields are optional Click Add to close the Details Panel window The new version of the organization appears in the Registry Objects area and the user is created Click Save in the Details area for the object Adding a Child Organization to an Organization An Organization can have one or more child organizations To add a child orga nization to an Organization follow these steps 1 In the Details
261. g customization file and lt schema gt is the name of the schema s you want to pass to the binding compiler 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 command line For more information about xjc compiler options in general see JAXB Com piler Options page 30 CUSTOMIZATION OVERVIEW 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 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 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 schemaLocati
262. g 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 269 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 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
263. g properties debug Whether or not debugging output is enabled editor The editor to use when the Admin Tool launches an interactive editor exception The exception stack trace if any from the immediately preceding exe cuted command locale The current locale verbose 100 ADMINISTERING THE SERVICE REGISTRY Whether or not verbose output is enabled Operands property The property whose current value is to be displayed The properties exception and locale can be displayed but you cannot use the set command to set them Example The following command displays the exceptions from the previous command admin gt show exception users Lists the current User objects Synopsis users Desc nption The users command lists the User objects currently in the Registry The output has the following format index URN lastname firstname In the output the index is a numeric value that you can use including the percent sign to refer to a user when you run the chown or cp command The lastname and firstname are the first and last names of the user OTHER ADMINISTRATION TASKS 101 Examples The following command displays the current users admin gt users 0 urn uuid 2702f889 3ced 4d49 82d1 e4cd846cb9e4 user test 1 urn uuid 85428d8e 1bd5 473b a8c8 b9d595f82728 Parker Miles 2 urn uuid 921284f0 bbed 4a4c 9342 ecaf 625f9d7 Operator Registry 3 urn uuid 977d9380 00e2 4ce8 9cdc d8bf6a4157be Brown Arth
264. g the Explore Menu Using the Search Menu Click Search in the menu area The Search form opens It contains the following components e Select Predefined Query drop down list e Name text field e Description text field e ClassificationSchemes tree Click Hide Search Form to close the Search form and clear the results area The next few sections describe how to use these components SELECTING A QUERY Selecting a Query The Select Predefined Query drop down list contains the items shown in Table 7 2 Table 7 2 Predefined Queries The default generic query which allows you to search by Basic Quer SA Query object type name description and classification Basic Query Case Sensitive Case sensitive version of Basic Query Finds all objects owned published by the user who makes FindAllMyObjects the query may take a long time if the user owns many objects GetCallersUser Finds the User object for the user who makes the query The default selection is Basic Query The following sections describe how to perform basic queries e Searching by Object Type e Searching by Name and Description e Searching by Classification Use the FindAllMyObjects and GetCallersUser queries to search for all the objects you have published and to view and modify data for the user you created when you registered Searching by Object Type The simplest search is by object type only The default choice in the Object Type drop
265. g the SubjectAccessor API XWS Security applications might require access to the authenticated subject of the sender from within the SEI implementation methods The SubjectAccessor API contains a single method public static Subject getRequesterSubject Object context throws XWSSecurityException public static Subject getRequesterSubject The getRequesterSubject Object context method returns the Subject if one is available or else it returns NULL The context argument to be passed into this method should either be a ServletEndpointContext which is available USEFUL XWS SECURITY COMMAND LINE TOOLS 197 with the SEI implementation class or a com sun xm wss ProcessingCon text For an example on how the SubjectAccessor is used to obtain the authen ticated sender subject refer to the PingImp1 java class in the jaas sample located at lt JWSDP_HOME gt xws security samples jaas sample server src sample The API for SubjectAccessor viewed from lt JWSDP_HOME gt xws secu rity docs api com sun xm1 wss SubjectAccessor html The getRequesterSubject method returns the requester subject from the context if available and returns null if not available This method should be used by the receiver response processing to access the subject of the requester This method will work only for the Synchronous Request Response Message Exchange Pattern SRRMEP For an example that uses this method see Dynamic Response Sample Application Useful XWS Sec
266. ger or EVENT_TYPE_DELETED 2 BusinessLifeCycleManager deletion methods Object was deprecated using the Li feCycleMan EVENT_TYPE_DEPRECATED 7 7 S ager deprecateObjects method Object was undeprecated using the Li feCycleMan EVENT_TYPE_UNDEPRECATED ager unDeprecateObjects method A new version of the object was created This event typically EVENT_TYPE_VERSIONED avi Ren happens when any of the object s attributes changes EVENT_TYPE_UPDATED Object was updated Object was approved using the Li feCycleManager EVENT_TYPE_APPROVED Imp1 approveObjects method implementation spe cific EVENT_TYPE_DOWNLOADED Object was downloaded implementation specific EVENT_TYPE_RELOCATED Object was relocated implementation specific DEVELOPING CLIENTS FOR THE SERVICE REGISTRY The following code fragment retrieves the audit trail for a registry object dis playing the type and timestamp of each event Collection events obj getAuditTrailQ String objName obj getName getValue Iterator eventIter events iterator while CeventIter hasNext AuditableEventImp1 ae AuditableEventImp1l eventIter nextQ int eType ae getEventType if CeType AuditableEvent EVENT_TYPE_CREATED System out print objName created else if CeType AuditableEvent EVENT_TYPE_DELETED System out print objName deleted else if CeType AuditableEvent EVENT_TYPE_DEPRECA
267. gt lt xs element name SymmetricKey type SymmetricKey_T gt lt xs choice gt lt xs element name CanonicalizationMethod type CanonicalizationMethod_T minOccurs 0 gt lt xs element name SignatureMethod type SignatureMethod_T minOccurs 0 gt lt xs sequence minOccurs 0 maxOccurs unbounded gt lt xs element name Target type Target_T minOccurs 0 maxOccurs unbounded gt lt xs element name SignatureTarget type SignatureTarget_T minOccurs 0 maxOccurs unbounded gt lt xs sequence gt lt xs sequence gt lt xs attribute name id type id_T use optional gt lt xs attribute name includeTimestamp type xs boolean use optional default true gt lt xs complexType gt lt xs complexType name CanonicalizationMethod_T gt lt xs attribute name algorithm type xs string use optional default http www w3 org 2001 10 xml exc c 14n gt lt xs complexType gt lt xs complexType name SignatureMethod_T gt lt xs attribute name algorithm type xs string use optional default http www w3 org 2000 09 xmldsig rsa shal gt lt xs complexType gt lt xs complexType name RequireSignature_T gt lt xs sequence minOccurs 0 maxOccurs 1 gt lt xs choice minOccurs 0 maxOccurs 1 gt lt xs element name X509Token type X509Token_T gt 110 A XWS SECURITY FORMAL SCHEMA DEFINITION lt xs element name SAMLAssertion type SAMLAssertion_T gt lt xs element name
268. hat use this element Table 4 28 provides a description of its attributes Table 4 28 Attributes of AlgorithmParameter Attributes of AlgorithmParameter Description name The name of the algorithm parameter Required 161 162 INTRODUCTION TO XML AND WEB SERVICES SECURITY Table 4 28 Attributes of AlgorithmParameter Continued Attributes of AlgorithmParameter Description yau The value of the algorithm parameter Required X509Token The lt X509Token gt element is used to specify the certificate to be used for encryp tion for the case of encryption or the certificate corresponding to the private key used for signing for the case of signature This element must not be speci fied if the lt SymmetricKey gt or lt SAMLAssertion gt sub elements are present Table 4 29 provides a description of its attributes Table 4 29 Attributes of X509Token Attributes of X509Token Description The id to be assigned to this token in the message This attribute is useful in referring the token from other places in the security configuration file Optional If specified it denotes the wsu Id to be assigned to the Secu rity Token Reference STR to be generated and inserted into the message The inserted STR would reference the X509 token certificateAlias The alias associated with the token certificate The reference mechanism to be used for referring to the X509 token certificate which was involved in t
269. have the com ment character beside them See SAML Interop Sample Configuration Files for more information on the security configurations options defined for this sample application 4 Build and run the application from a terminal window or command prompt e On the Application Server the command to build and run the applica tion is asant run sample e On the other containers the command to build and run the application is ant run sample DYNAMIC POLICY SAMPLE APPLICATION 255 Note To run the sample against a remote server containing the deployed endpoint use the run remote samp e target in place of the run samp1e target In this situa tion make sure that the endpoint host endpoint port http proxyHost http proxyPort and service url properties are set correctly in the build prop erties file as discussed in Setting Build Properties before running the sample If the application runs successfully you will see a message similar to the follow ing echo Running the client program java Sending Message Start java Sending Message End java Received Message Start java Received Message End java Hello to Duke You can view similar messages in the server logs lt SJSAS_HOME gt domains lt domain name gt logs server log lt TOMCAT_HOME gt logs launcher server log lt SJISWS_HOME gt lt Virtual Server Dir gt logs errors Dynamic Policy Sample Applicaton The
270. he request else if cb getRequest instanceof SignatureVerificationKeyCal lback X5 9IssuerSerialBasedRequest issuer serial request SignatureVeri ficationKeyCal lback X509I ssuerSerialBasedRequest request SignatureVeri ficationKeyCal lback X 509IssuerSerialBasedRequest cb getRequest locate and setX509Certificate on the request else throw unsupported else if callbacks i instanceof SignatureKeyCallback SignatureKeyCallback cb SignatureKeyCallback callbacks i if cb getRequest instanceof SignatureKeyCal lback DefaultPrivKk eyCertRequest default priv key cert req SignatureKeyCallback DefaultPrivKeyCertRequest request SignatureKeyCal lback DefaultPrivKeyCertRequest cb getRequest locate and set default privateKey and X509Certificate on request 192 INTRODUCTION TO XML AND WEB SERVICES SECURITY else if cb getRequest instanceof SignatureKeyCallback AliasPrivKeyCertRequest Alias priv key cert req SignatureKeyCallback AliasPrivKeyCertRequest request SignatureKeyCal lback AliasPrivKeyCertRequest cb getRequest locate and set default privateKey and X509Certificate on request else throw unsupported else if Ccallbacks i instanceof DecryptionKeyCallback DecryptionKeyCallback cb DecryptionKeyCallback callbacks i if C cb getRequest instanceof DecryptionKeyCal lback X509Subject KeyIdentifierBasedRequest ski req
271. he 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 Bind Choice and Fix Collides examples use example xsd rather than po xsd e po xml is the Purchase Order XML file containing sample 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 27 28 USING JAXB differences to highlight different JAXB concepts Note that the Bind Choice and Fix Collides examples use example xm 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 xml 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 Bind Choice and Fix Collides examples is an external binding declarations file that is passed to the JAXB binding compiler 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 a
272. he JDK Error DeployTask not found Solution Verify that the jwsdp home property in the build properties file for the sample is set correctly to the location where you installed the Java WSDP version 1 6 as described in Setting Build Properties A common error is to not escape the backslash character when running on the Microsoft Windows plat form Compiler Errors If you use a version of the Application Server prior to 2005Q1 for the container you may get compiler errors because this version of the Application Server has an earlier version of XWS Security bundled into it The compilation errors that you see are because these classes do not exist in the earlier version of XWS Security shipped in these earlier versions of the Application Server 202 INTRODUCTION TO XML AND WEB SERVICES SECURITY Further Information e Java 2 Standard Edition v 1 5 0 security information http java sun com j2se 1 5 0 docs guide security index html e Java Servlet specification http java sun com products servlet e Information on SSL specifications http wp netscape com eng security e OASIS Standard 200401 Web Services Security SOAP Message Security 1 0 http docs oasis open org wss 2004 0 1 oasis 20040 1 wss soap message security 1 0 pdf e XML Encryption Syntax and Processing http www w3 org TR xmlenc core e Digital Signatures Working Draft http www w3 org Signature e JSR 105 XML Digital Signature APIs http www jcp org en jsr det
273. he 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 76 USING JAXB J AXB Version Namespace and Schema Attributes 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 xmlIns xs http www w3 org 2001 XMLSchema gt lt jxb bindings schemaLocation po xsd node xs schema gt lt binding_declarations gt 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
274. he four scenarios You specify attachments as targets by specifying the value of the Content ID CID header of the attachment To do this set the type attribute to uri and specify the target value as cid lt part name gt where part name is the WSDL part name of the AttachmentPart The swa client xm1 file looks like this lt xwss JAXRPCSecurity xmIns xwss http java sun com xml ns xwss config gt lt xwss Service gt lt Port 1 SwA Scenario 1 Sign Attachment Only gt lt xwss Port name http xmlsoap org Ping Pingl gt lt xwss SecurityConfiguration dumpMessages true gt lt Note that in the lt Sign gt operation a Timestamp is exported in the security header and signed by default gt lt xwss Sign includeTimestamp false gt lt xwss X509Token certificateAlias xws security client gt lt xwss CanonicalizationMethod algorithm http ww w3 org 2001 10 xm1 exc cl14n gt lt xwss SignatureMethod algorithm http www w3 org 2000 09 xmldsig rsa shal gt lt xwss SignatureTarget type uri value cid foobar gt lt xwss DigestMethod algorithm http www w3 org 2000 09 xmldsig shal gt lt xwss Transform algorithm http docs oasis open org wss 2004 XX oasis 2004XX wss swa profile 1 0 Attachment Comp ete Transform gt lt xwss SignatureTarget gt lt xwss Sign gt lt xwss SecurityConfiguration gt lt xwss Port gt SWA SAMPLE CONFIGURATION FILES 245 lt
275. he message It looks like this lt xwss SecurityConfiguration dumpMessages true xmIns xwss http java sun com xml ns xwss config gt lt Note that in the lt Sign gt operation a Timestamp is exported in the security header and signed by default gt lt xwss Sign gt lt xwss X509Token certificateAlias xws security client keyReferenceType Identifier gt lt xwss Sign gt lt xwss SecurityConfiguration gt The sign rsign xm1 file looks like the signv1 xm1 file except that it requires a signature It looks like this lt xwss SecurityConfiguration dumpMessages true xmIns xwss http java sun com xml ns xwss config gt lt xwss Sign gt lt xwss X509Token certificateAlias xws security client gt lt xwss Sign gt lt xwss RequireSignature gt lt xwss SecurityConfiguration gt The str transform xm1 file uses a Security Token Reference STR Derefer ence Transform which is an option for referencing information to be signed Other methods for referencing information to be signed include referencing URIs IDs and XPaths Use an STR Transform when a token format does not allow tokens to be referenced using URIs or IDs and an XPath is undesirable 240 UNDERSTANDING AND RUNNING THE XWS SECURITY SAMPLE APPLICATIONS STR Transform allows you to create your own unique reference mechanism It looks like this lt xwss SecurityConfiguration dumpMessages true xmIns xwss http java sun com xml ns xw
276. he security opera tion in the outgoing messages The default value is Di rect The list of allowed values for this attribute and their descrip tion is as follows 1 Direct certificate is sent along with the message 2 Identifier subject key identifier extension value of the certificate is sent in the message 3 IssuerSerialNumber issuer name and serial number of the certificate are sent in the message keyReferenceType SEMANTICS OF SECURITY CONFIGURATION FILE ELEMENTS Table 4 29 Attributes of X509Token Continued Attributes of X509Token Description The type of encoding to be used for the token The default value is http docs oasis open org wss 2004 01 0asis 200401 wss soap message security 1 0 Base64Binary encodingType The type of value to expect The valueType can be X509v3 valueType X509PKIPathv1 or PKCS7 This release does not support PKCS7 Target Note In this release the Target sub element is deprecated and is supported only for backward compatibility The Target sub element is being replaced with Signature Target and EncryptionTarget The lt Target gt target_value lt Target gt sub element contains a string that can be used to identify the resource that needs to be signed or encrypted If a Target sub element is not specified the default value is a target that points to the con tents of the SOAP body of the message The value of this element is specified as a text node inside t
277. he simple sample uses the following properties look in config directory for alternate security configurations Client Security Config file client security config config dump client xm client security client xml client security client security client xml client security client security client security client xml client client client client client client security security security security security security config config user pass authenticate config config encrypted user pass client xm l config config encrypt usernameToken config config sign client xml config config encrypt client xml confi g config encrypt using symmkey confi g config sign encrypt client xm confi g config encrypt sign client xm confi g config sign ticket also client xm confi g config timestamp sign client xm confi g config flexiblec xm confi g config method level client xm Server Security Config file server security config config dump server xm server security server xml server security server security confi g config user pass authenticate confi g config encrypted user pass server xml confi g config encrypt usernameToken server xml server security server security server security server security server security server security server security server security confi g config sign server xm confi g config encrypt server xm conf
278. he values of properties con figurable with XWS Secu rity run time Refer to the API documenta tion at lt JWSDP_HOME gt xws security docs api com sun xml1 wss imp1 callback PropertyCal1 back htm for a list of con figurable properties and methods supported by this callback Request Inner Classes Defined Methods in the Request Classes This callback has been depre cated and disabled in this release To get similar function ality use the maxClockSkew and timestampFreshness Limit attributes on lt Requi re Timestamp gt or the maxClockSkew timestamp FreshnessLimit and max NonceAge attributes on lt Requi reUsernameToken gt 188 INTRODUCTION TO XML AND WEB SERVICES SECURITY Table 4 41 Summary of Callback classes and their Request types Continued Request Inner Methods in the Request Callback Description Classes Defined Classes The PrefixNamespaceMap pingCallback has been depre cated and disabled in this release When specifying XPath expressions for targets in XWS Security configuration files you are required to make use of the elongated syntax of the form local name Body and namespace uri http schemas xmlsoap org soap envelope etc if the prefix involved is anything other than the following 1 The prefix of the SOAP enve lope in the message 2 One of the following prefixes SOAP ENV env S11 to mean http schemas xml1 soap org soap envelope 3 Prefix ds
279. hip between the subject of each SAML subject statement and the entity provid ing the evidence to satisfy the confirmation method defined for the statements 250 UNDERSTANDING AND RUNNING THE XWS SECURITY SAMPLE APPLICATIONS The two methods for establishing this correspondence are Holder of Key HOV and Sender Vouches SV For more information on these confirmation methods read SAML Token Profile 1 0 The following is a summary of each of the SAML interop scenarios e Scenario 1 Sender Vouches Unsigned The request contains a minimal sender vouches SAML assertion with no optional elements included There are no signatures or certificates required The response does not contain a security header In this scenario there is no technical basis for trust because the messages are sent in the clear with no content or channel protection This scenario is intended only to demonstrate message structure interoperability and is not intended for production use e Scenario 2 Sender Vouches Unsigned SSL sample not provided The request contains a sender vouches SAML assertion There are no signatures required This scenario is tested over SSL and certificates are required to support SSL at the transport layer The response does not con tain a security header In this scenario the basis of trust is the Requester s client certificate used to establish the SSL link The Responder relies on the Requester who vouches for the contents
280. his element You can specify attachments as targets by setting the type attribute to uri and specifying the target value as cid lt part name gt which specifies the value of the Content ID CID header of the attachment When the Content ID is not know until runtime such as when auto generated CIDs are run under JAX RPC the attachment can be referenced by setting the type attribute to uri and specifying the target value as attachmentRef lt part name gt where part name is the WSDL part name of the AttachmentPart Auto generated CIDs in JAX RPC following the form lt partname gt lt UUID gt lt Domain gt The special value cid can be used to refer to all attachments of a SOAPMessage 163 164 INTRODUCTION TO XML AND WEB SERVICES SECURITY The attributes of the lt Target gt element are described in Table 4 30 Table 4 30 Attributes of Target Indicates the type of the target value Default value is qname The list of allowed values for this attribute and their descrip tion is as follows 1 qname If the target element has a local name Name and a namespace URI some uri the target value is some uri Name 2 xpath Indicates that the target value is the xpath of the target element 3 uri If the target element has an id some id then the tar get value is some id Indicates whether the complete element or only the contents needs to be encrypted or is required to be encrypted The default value is true
281. http xmlsoap org Ping Ping gt lt Port level security configuration Takes precedence over the service level security configuration gt lt xwss SecurityConfiguration dumpMessages true gt lt xwss Operation name http xmlsoap org Ping Ping gt lt Operation level security configuration Takes precedence over port level and service level security configurations gt lt xwss SecurityConfiguration dumpMessages true gt 223 224 UNDERSTANDING AND RUNNING THE XWS SECURITY SAMPLE APPLICATIONS lt xwss UsernameToken name Ron password noR digestPassword false useNonce false gt lt xwss Sign gt lt xwssS Target type qname gt http xmlsoap org Ping ticket lt xwss Target gt lt xwssS Target type qname gt http xmlsoap org Ping text lt xwss Target gt lt xwss Sign gt lt xwss Encrypt gt lt xwss X509Token certificateAlias slas gt lt xwss Encrypt gt lt xwss SecurityConfiguration gt lt xwss Operation gt lt xwss Operation name http xmlsoap org Ping PingQ gt lt xwss SecurityConfiguration dumpMessages true gt lt xwss Encrypt gt lt xwss X509Token certificateAlias slas gt lt xwss Encrypt gt lt xwss SecurityConfiguration gt lt xwss Operation gt lt xwss Port gt lt xwss Port name http xmlsoap org Ping Ping0 gt lt xwss SecurityConfiguration dumpMessages true gt lt xwss Encrypt gt lt xwss X509Token certificateAlias slas gt
282. i tional implementation specific method setFederation This method takes as its argument the unique identifier of the federation you want to query public void setFederation java lang String federationId throws JAXRException Therefore before you can call this method you must obtain the unique identifier value To do so first call BusinessQueryManagerImp1 findObjects to locate the federation by name In this code you would substitute the actual name of the federation for the string NameOfFederation Collection namePatterns new ArrayListQ namePatterns add NameOfFederation Find objects with name NameOfFederation BulkResponse response bqm findObjects Federation null namePatterns null null null null Then iterate through the collection which should have only one member and retrieve the key value String fedId federation getKeyQ getIdQ Finally create the query call setFederated and setFederation and execute the query QueryImp1 query QueryImp1 dqm createQuery Query QUERY_TYPE_SQL qString query setFederated true query setFederation fedId response dqm executeQuery query PUBLISHING OBJECTS TO THE REGISTRY Using Federated Queries Example For an example of the use of a federated query see lt INSTALL gt registry sam ples query federation src JAXRQueryFederation java This example performs two queries a declarative query and a stored query on every federation it find
283. i g config sign encrypt server xm confi g config encrypt sign server xm confi g config sign ticket also server xm confi g config timestamp sign server xm confi g config flexibles xm confi g config method level server xm As you can see from this example several security scenarios are listed in the build properties file To run a particular security configuration option simply uncomment one of the entries for a client configuration file uncomment the cor responding entry for the server configuration file and comment all of the other options In general the client and server configuration files should match However in some cases more than one client configuration can be used with a server config How Do I SPECIFY THE SECURITY CONFIGURATION FOR THE BUILD FILES uration For example either encrypt using symmkey client xm or encrypt client xml can be used with encrypt server xm1 This combina tion works because the server requirement is the same the body contents must be encrypted when the client side security configuration is either encrypt using symmkey client xml or encrypt client xml The difference in the two client configurations is the key material used for encryption After the property has been defined in the build properties file you can refer to it from the file that contains the asant or ant targets which is build xm1 When you create an asant or ant target for JAX RPC clients and services you use the w
284. ibute Event qname ISBN attributes null StartElement namespaces null isCData false data 81 40 34319 4 n t Characters IsWhiteSpace false qname ISBN EndElement namespaces null qname Cost attributes currency gt INR StartElement namespaces null isCData false data 11 50 n t Characters IswWhiteSpace 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
285. icationLink object To add a Specifica tionLink to a ServiceBinding follow these steps 1 In the Details area for the ServiceBinding click the SpecificationLinks tab The SpecificationLinks table appears 2 Click Add A Details Panel window opens 3 In the Name field type a name for the SpecificationLink 4 Optionally type a description of the SpecificationLink in the Description field 302 USING THE SERVICE REGISTRY WEB CONSOLE 5 In the Usage Description field type a usage description for the usage parameters if there are any 6 In the Usage Parameters field type the usage parameters if there are any 7 Click Add to close the Details Panel window The new version of the object appears in the Registry Objects area 8 Click Save in the Details area for the object Adding a Child Conceptto a Classification Scheme or Concept A ClassificationScheme normally has numerous child concepts which can in turn have child concepts To add a child concept to a ClassificationScheme fol low these steps 1 In the Details area for the ClassificationScheme click the Concepts tab The Concepts table appears 2 Click Add A Details Panel window opens In the Name field type a name for the concept Optionally type a description of the concept in the Description field In the Value field type a value for the concept Click Add to close the Details Panel window Nn W The new version of the ob
286. ient 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 elements 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 89 90 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 doe
287. ific XMLInputFactory implementation class to load by using the following lookup procedure 1 Use the javax xml stream XMLInputFactory system property 2 Use the 1ib 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 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 3 4 lists the prop 99 100 STREAMING API FOR XML erties supported by XMLInputFactory See the StAX specification for a more detailed listing Table 3 4 XMLInputFactory Properties javax xml stream is Validating Turns on implementation specific validation Required Requires the processor to coalesce javax xml stream isCoalescin J 8 adjacent character data Turns off namespace support All implementations javax xml stream isNamespaceAware must support namespaces supporting non namespace aware documents is optional 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 isReplacingEntityReferences Required Requires the processor to resolve exter javax xml stream isSupportingExternalEnti
288. ignature 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 to 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
289. igned 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 newInstanceQ 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 279 280 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
290. igning is to be retrieved given the public key Methods in the Request Classes The following four methods are present in all Request Classes of this Cal back public void setPrivateKey PrivateKey privateKey public PrivateKey getPri vateKey public void setx509Certificate X509Certificate certifi cate public X509Certificate getx509CertificateQ WRITING SECURITYENVIRONMENTHANDLERS 181 Table 4 41 Summary of Callback classes and their Request types Continued Callback Signa ture Verifi cation Key Callback Description Obtains the certificate required for signature verifi cation There are currently two situations in which XWS Security would require this Callback to resolve the certificate 1 When the signature to be verified references the key using an X 509 Subject KeyIdenti fier For exam ple when the sender specifies the attribute xwss keyRef erenceType Identi fier on the xwss X509Token child of the xwss Sign element 2 When the signature to be verified references the key using an X 509 IssuerSe rialNumber For example when the sender specifies the attribute xwss keyRefer enceType IssuerSeri alNumber on the xwss X509Token child of the xwss Sign element 3 When ds KeyInfo contains a key value use the public key to obtain the X 509 cer tificate Accordingly there are three Request inner classes with which a SignatureVeri ficationKeyCallback can
291. il Calendar xsd anySimpleType java lang String Default Binding Rules Summary The JAXB binding model follows the default binding rules summarized below Bind the following to Java package e XML Namespace URI Bind the following XML Schema components to Java content interface e Named complex type e Anonymous inlined type definition of an element declaration Bind to typesafe enum class e A named simple type definition with a basetype that derives from xsd NCName and has enumeration facets Bind the following XML Schema components to a Java Element interface e A global element declaration to a Element interface e Local element declaration that can be inserted into a general content list Bind to Java property e Attribute use e Particle with a term that is an element reference or local element decla ration Bind model group with a repeating occurrence and complex type defini tions with mixed content type to e A general content property a List content property that holds Java instances representing element information items and character data items CUSTOMIZING JAXB BINDINGS Customizing J AXB Bindings The default JAXB bindings can be overridden at a global scope or on a case by case basis as needed by using custom binding declarations As described previ ously JAXB uses default binding rules that can be customized by means of bind ing declarations made in either of two ways e As inline a
292. ing a password that would be conveyed to the user by the authority After receiving the PKCS 12 formatted file you would import this key pair cer tificate private key pair into your private keystore using the pkcs12import tool The result of the import is that the private key and the corresponding certificate in the PKCS 12 file are stored as a key entry inside the keystore associated with some alias The pkcs12import tool can be found in the directory lt JWSDP_HOME gt xws secu rity bin and can be run from the command line by executing pkcs12import sh on Unix systems or pkcs12import bat on Windows sys tems The options for this tool listed in Table 442 Table 4 42 Options for pkcs12import tool Option Description Required The location of the PKCS 12 file to be file pkcs12 file imported The password used to protect the PKCS 12 file The user is prompted for this password if this option is omitted pass pkcs12 pass word Location of the keystore file into which to import the contents of the PKCS 12 file If no value is given defaults to user home keystore keystore keystore file storepass store The password of the keystore User is prompted for password the password of the truststore if this option is omitted The password to be used to protect the private key inside the keystore The user is prompted for this password if this option is omitted keypass key pass word
293. ing as the single child to a SOAP request The value is the organization that has developed the software and the number of the scenario for example in this application the value is Sun Micro systems Scenario 1 The Responder returns a PingResponse element with a value of the same string Each interaction includes a SOAP attachment secured via one of the content level security mechanisms described in the WSS SwA Pro file THE SWA INTEROP SCENARIOS 243 The following is a summary of each of the SwA interop scenarios demonstrated in this sample application You will need the numbers for the scenarios when you run the sample application 1 Scenario 1 Attachment Signature Scenario 1 tests the interoperability of a signed attachment using an X 509 certificate The certificate used to verify the signature shall be present in the SOAP header No security properties are applied to any part of the SOAP envelope 2 Scenario 2 Attachment Encryption The SOAP request has an attachment that has been encrypted The encryption is done using a symmetric cipher The symmetric encryption key is further encrypted for a specific recipient identified by an X 509 cer tificate The certificate associated with the key encryption is provided to the requestor out of band No security properties are applied to any part of the SOAP envelope 3 Scenario 3 Attachment Signature and Encryption The SOAP request contains an attachment that has
294. ing description exLink getDescription getValue System out printInC External link description is description String externalURI exLink getExternalURIQ System out printInC External link URI is externalURI Some of the examples have a showExternalLinks method that uses this code See for example JAXRQueryByName java in Finding Objects by Name Example page 16 28 DEVELOPING CLIENTS FOR THE SERVICE REGISTRY Retrieving the Slots foran Object Slots are arbitrary attributes that you can create for an object Use the Registry Object getSlots method to retrieve a Collection of the object s slots For each slot you can retrieve its name values and type The name of a Slot object is a String not an InternationalString and a slot has a Collection of val ues The following fragment retrieves and displays an object s slots Collection slots object getSlotsQ Iterator slotIter slots iterator while slotIter hasNextQ Slot slot Slot slotIter nextQ String name slot getName System out printIn C Slot name is name Collection values slot getValuesQ Iterator valIter values iterator int count 1 while valiIter hasNextQ String value String valiter nextQ System out printInC Slot value count 4 value String type slot getSlotTypeQ if type null System out printInC Slot type is type Some of the examples have a showSlots method that u
295. ing unmarshal operations Validator v jc createValidator boolean valid v validateRoot po System out printIn valid 7 The default validation event handler processes a validation error generates output to system out and then an exception is thrown catch ValidationException ue System out printIn Caught ValidationException catch JAXBException je je printStackTraceQ catch IOException ioe joe printStackTraceQ Sample Output Running java Main for this example produces the following output DefaultValidationEventHandler ERROR 5 does not satisfy the positiveInteger type Caught ValidationException 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 43 which focus on the Java code in the respective Main java class files the examples here focus on customiza WHY CUSTOMIZE 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 w
296. ion getParentOrganization method retrieves an organiza tion s parent In the following fragment chorg is a child organization Organization porg chorg getParentOrganization The Organization getChildOrganizations method retrieves a Collection of the organization s children In the following fragment org is a parent organiza tion Collection children org getChildOrganizationsQ The Organization getDescendantOrganizations method retrieves multiple generations of descendants while the Organization getRootOrganization method retrieves the parentless ancestor of any descendant For an example of retrieving an organization hierarchy see Creating and Retriev ing an Organization Hierarchy Example page 53 RETRIEVING INFORMATION ABOUT AN OBJECT 33 Retrieving the Audit Trail of an Object Whenever an object is published to the Registry and whenever it is modified in any way JAXR creates another object called an AuditableEvent and adds the event to the audit trail for the published object The audit trail contains a list of all the events for that object To retrieve the audit trail call RegistryOb ject getAuditTrail You can also retrieve the individual events in the audit trail and find out their event types JAXR supports the event types listed in Table 8 5 Table 8 5 AuditableEvent Types EVENT_TYPE_CREATED Object was created and published to the registry Object was deleted using one of the Li feCycleMana
297. ion that included the regis tries of other European health ministries About 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 JAXR ARCHITECTURE The current version of the JAXR specification includes detailed bindings between the JAXR information model and the ebXML Registry specifications You can find the latest version of the JAXR specification at http java sun com xml downloads jaxr htm The Service Registry includes a JAXR provider that implements the level 1 capa bility profile which allows full access to ebXML registries The ebXML specifi cations and the JAXR specification are not in perfect alignment because the ebXML specifications have advanced beyond the JAXR specification For this reason the JAXR provider for the Registry includes some additional implemen tation specific methods that implement the ebXML specifications and that are likely to be included in the next version of the JAXR specification 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 J
298. ion to another or use the Organiza tion addChildOrganizations method to add a Collection of organizations to another Creating an Organization Examples For examples of creating an organization see JAXRPublishOrg java and JAXR PublishOrgNoPC java in the directory lt INSTALL gt registry samples orga nizations src The JAXRPublishOrg example creates an organization its primary contact and a service and service binding It displays the unique identifiers for the organiza tion user and service so that you can use them later when you delete the objects This example creates a fictitious User as the primary contact for the organiza tion The other example JAXRPublishOrgNoPC does not set a primary contact for the organization In this case the primary contact by default is the User who is authenticated when you run the program To run the examples follow these steps 1 Go to the directory lt INSTALL gt registry samples organizations 2 Type the following commands ant pub org ant pub org nopc CREATING OBJECTS 53 Creating and Retrieving an Organization Hierarchy Example For examples of publishing and retrieving an organization hierarchy see the examples lt INSTALL gt registry samples organizations src JAXRPub lishOrgFamily java and lt INSTALL gt registry samples organizations src JAXRQueryOrgFami ly java To run the examples follow these steps 1 Go to the directory lt INSTALL gt registry samples organ
299. ionType String schemeName AssociationType ClassificationScheme cScheme bqm findClassificationSchemeByName null schemeName After you locate the classification scheme you call the LifeCycleMan ager createClassification method specifying three arguments the classifi cation scheme and the name and value of the concept Classification classification blcm createClassification cScheme Extends Extends An alternative method is to call BusinessQueryManager findConcepts or BusinessQueryManagerImp1 findObjects with a Concept argument locate the concept you wish to use and call another form of createClassifi cation with the concept as the only argument Classification classification blcm createClassification concept After creating the classification you call RegistryObject addClassification to add the classification to the object object addClassification classification To add multiple classifications you can create a Collection add the classifica tion to the Collection and call RegistryObject addClassifications to add the Collection to the object Adding Classifications Example For an example of adding classifications to an object see lt INSTALL gt registry samples publish object src JAXRPublishObject java This example cre ates an organization and adds a number of objects to it To run the example fol low these steps 1 Go to the directory lt INSTALL gt registry samples publish ob
300. ip of the selected objects to the user specified by the URN urn uuid 26aal7e6 d669 4775 bfe8 a3a484d3e079 admin gt chown urn uuid 26aal17e6 d669 4775 bfe8 a3a484d3e079 The following command changes the ownership of the selected objects to the user with the number 2 in a preceding users command admin gt chown 2 cp Copies files and folders into the Registry Synopsis cp owner URN index exclude pattern pattern Desc nption The cp command copies files and folders into the Registry as RegistryPackage and ExtrinsicObject objects respectively CP The local directory on the local file system from which to copy files and folders defaults to the current directory from which you started the Admin Tool You can use the localdir option to change the local directory when you start the Admin Tool or you can use the 1cd command to change it after the Admin Tool has started You can get the absolute path of the current local directory using the show localdir command The command is recursive That is if you specify a directory the command cop ies all the files and folders under the directory Options Sets the owner of the copied registry objects to the user specified by the URN or index argument See the description of the chown command for a description of these arguments You must have the role of administrator to specify an owner other than yourself exclude Copies all files except those whose names cont
301. iption svc Collection serviceBindings svc getServiceBindings Iterator sbIter serviceBindings iteratorQ while sbIter hasNextQ ServiceBinding sb ServiceBinding sbIter nextQ System out printIn Binding name getName sb System out printIn Binding description getDescription sb System out printIn C Access URI sb getAccessURI Collection specLinks sb getSpecificationLinks Iterator slIter specLinks iteratorQ while slIter hasNextQ 31 DEVELOPING CLIENTS FOR THE SERVICE REGISTRY SpecificationLink sl SpecificationLink slIter nextQ RegistryObject ro sl getSpecificationObjectQ System out printInC Specification link object of type ro getObjectType System out printInC Usage description sl getUsageDescription getValueQ Collection ups sl getUsageParameters Iterator upIter ups iteratorQ while CupIter hasNext String up String upIter nextQ System out printIn Usage parameter up The example Retrieving Organization Attributes Example page 30 also dis plays the services and service bindings for the organizations it finds Retrieving an Organization Hierarc hy JAXR allows you to group organizations into families One organization can have other organizations as its children and these can in turn have children Therefore any given organization may have a parent children and descendants The Organizat
302. is Callback public void setx509Certificate X509Certificate cer tificate public X509Certificate getx509Certificate The following methods are present in the AliasSymmet ricKeyRequest class of this Callback public void setSymmet ricKey javax crypto SecretKe y symmetricKey public javax crypto SecretKey getSymmetricKey WRITING SECURITYENVIRONMENTHANDLERS 183 Table 4 41 Summary of Callback classes and their Request types Continued Callback Decryp tion Key Callback Description Obtains the symmetric key to be used for decrypting the encrypted data or obtaining the private key for decrypting the encrypted random sym metric key that was sent with the message along with the encrypted data There are currently four situ ations in which XWS Secu rity will require this Callback to perform decryption 1 When the EncryptedKey references the key used for encrypting the symmetric key using an X 509 Sub jectKeyIdenti fier For example when the sender specifies the attribute key ReferenceType Identi fier on the xwss X509Token child of the xwss Encrypt element 2 When the Encrypted Key references the key used for encrypting the symmetric key using an X 509 Issu erSerialNumber For example when the sender specifies the attribute key ReferenceType Issu erSerialNumber on the xwss x509Token child of xwss Encrypt element Request Inner Classes Defined 1 X509Su
303. is supplied as the next to last argument of the findObjects method ClassificationScheme cScheme null cScheme bqm findClassificationSchemeByName null NASDAQ ExternalIdentifier extId blcm createExternalIdentifier cScheme Sun SUNW Collection extIds new ArrayListQ extIds add extId perform query BulkResponse response bqm findObjectsC RegistryObject null null null null extIds null Collection objects response getCollection Finding Objects by Extemal Identifier Example For an example of finding objects by external identifier see the example lt INSTALL gt registry samples query external identifier src JAXRQue ryByExternalIdentifier java which searches for objects that use the NAS DAQ classification scheme To run the example follow these steps 1 Go to the directory lt INSTALL gt registry samples query external identifier 2 Type the following command ant run FINDING OBJECTS BY EXTERNAL LINK This example is not likely to produce results unless you first run the publish object example described in Adding Classifications Example page 48 Finding Objects by Extemal Link Finding objects by external link does not require the use of a classification scheme but it does require you to specify a valid URI The arguments to the createExternalLink method are a URI and a description If the link you specify is outside your firewall you also need to specify the sys
304. is 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 gt lt jxb nameXm1Transform gt lt jxb schemaBindings gt 77 78 USING JAXB 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 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 customiza
305. iscussed in Setting Build Properties before running the sample If the application runs successfully you will see a message similar to the follow ing echo Running the sample TestClient program java Service URL http localhost 8080 jaassample Ping java Username read Ron java Password read noR java INFO Sending Message Start java lt xml version 1 0 encoding UTF 8 gt java lt env Envelope xmIns env http schemas xmlsoap org soap envelope xmins enc http schemas xmlsoap org soap encoding xmins ns0 http xmlsoap org Ping xmIns xsd http www w3 org 2001 XMLSchema xmIns xsi http www w3 org 2001 XMLSchema instance gt java lt env Header gt java lt wsse Security xmlns wsse http docs oasis open org wss 2004 01 o0asis 200401 wss wssecurity secext 1 xsd env mustUnderstand 1 gt java lt wsse UsernameToken gt java lt wsse Username gt Ron lt wsse Username gt java lt wsse Password gt lt wsse Password gt java lt wsse Nonce EncodingType http docs oasis open org wss 2004 01 oasis 200401 wss soap message security 1 0 Base64Binary gt qdKj 8WLOU3r21rcgO0iM4H76H lt wsse Nonce gt java lt wsu Created xmIns wsu http docs oasis open org wss 2004 01 o0asis 200401 wssS wssecurity uti lity 1 0 xsd gt 2004 11 05T02 07 46Z lt wsu Created gt java lt wsse UsernameToken gt java lt wsse Security gt java lt env Header gt
306. ishing objects with JAXR 4 querying with JAXR 10 removing objects 67 saving objects 56 starting 7 storing items in the repository 60 symmetric key encryption 218 244 classification T targets xml file JAXR examples 5 telephone numbers adding to organizations or us ers 298 TelephoneNumber interface 14 retrieving objects 28 timestamp 155 Timestamp element discussion 152 tokens security 128 UsernameTokens 130 truststore files for XWS Security samples 134 INDEX 209 typographical conventions xvi U UDDI registries 2 unDeprecateObjects method LifeCycleManager interface 66 undeprecating registry objects 302 65 example 66 unique identifiers finding objects by 22 retrieving 25 User interface 13 creating objects 53 retrieving object attributes 28 user name specifying on command line 71 UserName Token verification 211 Username Token Verification 130 UserName tokens 131 UsernameCallback 186 UsernameTokens 130 users adding email addresses 299 adding postal addresses 298 adding telephone numbers 298 adding to organizations 299 adding to registry 78 listing 100 users command 100 Vv v command line option 73 verbose command line option 73 verbose property displaying value 99 setting 97 verifying SOAP messages 128 version information retrieving 34 W Web Console starting 284 wildcards using 74 using in JAXR queries 14 using in searches 288 wscompile command 134 173 with XWS Security
307. ity configuration clientConfig new java io FileInputStream new java io File System getProperty client configfile read server side security configuration serverConfig new java io FileInputStream new java io File System getProperty C server configfile catch Exception e e printStackTraceQ throw e null null Create a XWSSProcessFactory XWSSProcessorFactory factory XWSSProcessorFactory newlInstance Create XwWSSProcessor to secure outgoing soap messages Sample SecurityEnvironment is configured to use client side keystores XWSSProcessor cprocessor factory createForSecurityConfiguration clientConfig new SecurityEnvironmentHandler client Create XWSSProcessor to veriy incoming soap messages Sample SecurityEnvironment is configured to use server side keystores XWSSProcessor sprocessor factory createForSecurityConfiguration serverConfig new SecurityEnvironmentHandler C server try API SAMPLE CLIENT CODE 235 clientConfig closeQ serverConfig close catch Exception ex ex printStackTrace return for int i 0 i lt 1 i create SOAPMessage SOAPMessage msg MessageFactory newInstance createMessage SOAPBody body msg getSOAPBody SOAPBodyElement sbe body addBodyElement SOAPFactory newInstance createName StockSymbol http fabrikam123 com payloads sbe addTextNode QQQ Create processing context
308. iv key cert req SignatureKeyCallback AliasPrivKeyCertR equest request SignatureKeyCal lback AliasPrivKeyC ertRequest cb getRequestQ locate and set default privateKey and X509Certificate on request else throw unsupported 196 INTRODUCTION TO XML AND WEB SERVICES SECURITY else throw unsupported Similarly an application dealing only with UsernameToken but not signature or encryption requirements can simply throw UnsupportedCal 1lbackException for all non username related callbacks The SecurityEnvironmentHandler implementation for the simple sample is located in the directory lt JWSDP_HOME gt xws security samples simple src com sun xm1 wss sample The simple sample uses the same SecurityEnvi ronmentHand1er for both the client and server side The jaas sample requires a different set of callbacks to be handled on the client and server side The CallbackHandlers for the jaas samp1e are located in the directory lt JWSDP_HOME gt xws security samples jaas sample src com sun xml1 wss sample The two CallbackHandlers defined for the jaas sam ple are e A ClientSecurityEnvironmentHandler that handles only the Usern ameCallback and PasswordCallback for retrieving the username and password to be sent in a WSS UsernameToken e A ServerSecurityEnvironmentHandler that handles only the Pass wordValidationCallback to validate the username password pair that it received in the WSS UsernameToken Usin
309. ivateCredentials permission javax security auth PrivateCredentialPer mission read permission javax security auth AuthPermission getSub ject permission javax security auth AuthPermission createLoginContext XwS_SECURITY_SERVER 5 Save and exit all files 6 Restart the Application Server Running the J AAS Sample Application To run the jaas sample application follow these steps 1 Follow the steps in Setting Up For the JAAS Sample 2 Start the selected container and make sure the server is running To start the Application Server a From a Unix machine enter the following command from a terminal window asadmin start domain domain1 b From a Windows machine choose Start Programs Sun Microsys tems Application Server Start Default Server 3 Build and run the application from a terminal window or command prompt e On the Application Server the command to build and run the applica tion is asant run sample e On the other containers the command to build and run the application is ant run sample Note To run the sample against a remote server containing the deployed endpoint use the run remote samp1e target in place of the run samp e target In this situa tion make sure that the endpoint host endpoint port http proxyHost RUNNING THE JAAS SAMPLE APPLICATION 231 http proxyPort and service url properties are set correctly in the build prop erties file as d
310. izard 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 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 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 identifier
311. izations 2 Type the following command to publish the organizations ant pub fam 3 Type the following command to retrieve the organizations you published ant query fam Creating Users If you create an organization without specifying a primary contact the default primary contact is the User object that created the organization that is the user whose credentials you set when you created the connection to the Registry However you can specify a different user as the primary contact A User is also a complex type of registry object It normally includes the following attributes in addition to those common to all objects e A PersonName object e One or more PostalAddress objects e One or more TelephoneNumber objects e One or more EmailAddress objects e One or more URL objects representing the user s home page The following code fragment creates a User and then sets that User as the pri mary contact for the organization This User has a telephone number and email address but no postal address Create primary contact set name User primaryContact blcm createUser String userId primaryContact getKey getIdQ System out printInC User URN is userId PersonName pName blcm createPersonName Jane M Doe primaryContact setPersonName pName Set primary contact phone number 54 DEVELOPING CLIENTS FOR THE SERVICE REGISTRY TelephoneNumber pctNum blcm createTelephoneNumber pctNum setCountryCode
312. ject 2 Type the following command ant run CREATING OBJECTS Adding Extemal Identifiers to Objects To add an external identifier to an object follow these steps 1 Find or create the classification scheme to be used 2 Create an external identifier using the classification scheme To create external identifiers you use an external classification scheme which is a classification scheme without a concept hierarchy You specify a name and value for the external identifier The database supplied with the Registry does not include any external classifica tion schemes so before you can use one you must create it using code like the following ClassificationScheme extScheme blcm createClassificationScheme NASDAQ OTC Stock Exchange To find an existing classification scheme you typically call the BusinessQuery Manager findClassificationSchemeByName method as described in Adding Classifications to Objects page 47 For example the following code fragment finds the external classification scheme you just created ClassificationScheme extScheme bqm findClassi ficationSchemeByName null NASDAQ To add the external identifier you call the LifeCycleManager createExter nalIdentifier method which takes three arguments the classification scheme and the name and value of the external identifier Then you add the external iden tifier to the object ExternalIdentifier extId blcm createExternalIdentifi
313. ject appears in the Registry Objects area 7 Click Save in the Details area for the object Changing the State of Objects In addition to saving editing and removing objects you can perform the follow ing actions on them if you are the owner or are otherwise authorized to do so e Approval e Deprecation e Undeprecation These features are useful in a production environment if you want to establish a version control policy for registry objects For example you can approve a ver REMOVING OBJECTS sion of an object for general use and deprecate an obsolete version before you remove it If you change your mind after deprecating an object you can undepre cate it You perform all these actions in the Search Results area e To approve an object select it and click the Approve button A message verifying the approval appears and the event is added to the Audit Trail e To deprecate an object select it and click the Deprecate button A message verifying the deprecation appears and the event is added to the Audit Trail e To undeprecate an object select it and click the Undeprecate button A message verifying the undeprecation appears and the event is added to the Audit Trail Removing Objects To remove an object you own from the Registry select the object and click the Delete button If the object is an extrinsic object you have two choices e Choose Delete Object and Repository Item the default from the Deletion
314. jects Slots are arbitrary attributes so the API provides maximum flexibility for you to create them You can provide a name one or more values and a type The name and type are String objects The value or values are stored as a Collection of String objects but the LifeCycleManager createSlot method has a form that allows you to specify a single String value For example the following code fragment creates a slot using a String value then adds the slot to the object String slotName Branch String slotValue Paris String slotType City Slot slot blcm createSlot slotName slotValue slotType org addSlot slot CREATING OBJECTS The example lt INSTALL gt registry samples pub1lish object src JAXRPub lishObject java described in Adding Classifications Example page 48 also adds a slot to an object Creating Organizations An Organization object is probably the most complex registry object It nor mally includes the following attributes in addition to those common to all objects e One or more PostalAddress objects e One or more TelephoneNumber objects e A PrimaryContact object which is a User object A User object normally includes a PersonName object and collections of TelephoneNumber Emai lAddress and PostalAddress objects e One or more Service objects and their associated ServiceBinding objects An organization can also have one or more child organizations which can in turn have children t
315. kage objects that each contain other RegistryOb ject and RegistryPackage objects The default is the RegistryPackage that is defined for all users data registry userData sqlselect Execute SQL_statement to select registry objects This should be a com plete SQL statement that starts with select The SQL statement must be enclosed in quotation marks but it does not have to be terminated by a semicolon v verbose Specifies the verbose output of status messages Using the Admin Tool This section covers the following topics Permissions Displaying Exceptions Identifying Registry Objects The Effect of Locale on Specifying Names Case Sensitivity Permissions When you use the Admin Tool you can perform only those actions that are allowed for the user whose alias and password you specified when you started the tool Only a user with the role of administrator can perform certain com mands chown for example 73 74 ADMINISTERING THE SERVICE REGISTRY Displaying Exceptions The Admin Tool enables you to avoid viewing long stack traces when a com mand fails When a command fails the Admin Tool prints the first line of the stack trace and the following message An error occurred when executing the function Use the show exception command to view messages If you need more information execute the show exception command next to see the full stack trace The show exception command always displays the
316. kages BusinessQueryManager findRegistryPackages Service Provides information on a service May have a set of Service Binding objects Finder method BusinessQueryMan ager findServices JAXR INFORMATION MODEL INTERFACES 13 Table 8 2 JAXR RegistryObject Subinterfaces Continued Represents technical information on how to access a Service ServiceBinding Getter finder methods Service getServiceBindings BusinessQueryManager findServiceBindings Provides a dynamic way to add arbitrary attributes to Regis tryObject instances Getter methods RegistryOb ject getSlot RegistryObject getSlots Provides the linkage between a ServiceBinding and one of its technical specifications that describes how to use the service using the ServiceBinding Getter method Servi ceBind ing getSpecificationLinks Speci ficationLink Provide information about registered users within the registry User objects are affiliated with Organization objects Getter methods Organization getUsers Organiza tion getPrimaryContact Table 8 3 lists the other interfaces supported by the JAXR information model These interfaces provide attributes for the main registry objects They do not themselves extend the RegistryObject interface Table 8 3 JAXR Object Types Used as Attributes Represents an email address A User may have an Emai 1Ad Emai 1Add mgr ae dress Getter method User getEmailAddresses Represents a String tha
317. ld be one that you created Removing Objects From the Registry and Repository A registry allows you to remove from it any objects that you have submitted to it You use the object s ID as an argument to the LifeCycleManager deleteOb jects method The following code fragment deletes the object 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 Collection keys new ArrayListQ keys add key BulkResponse response blcm deleteObjects keys Collection exceptions response getException if exceptions null System out printInC Objects deleted Collection retKeys response getCollection Iterator keyIter retKeys iteratorQ javax xml registry infomodel Key orgKey null if CkeyIter hasNextQ orgKey javax xml registry infomodel Key keyIter nextQ id orgKey getIdQ System out printInC Object key was id Deleting an Organization does not delete the Service and User objects that belong to the Organization You must delete them separately Deleting a Service object deletes the ServiceBinding objects that belong to it and also the SpecificationLink objects that belong to the ServiceBinding objects Deleting the Speci ficationLink objects however does not delete the associated ExtrinsicObject instances and their associated repository items You must delete the extrinsic objects separatel
318. le programatically Configuring Your Environment for Running the Samples The instructions for configuring your environment are basically the same as those required for running the JWSDP in general In addition to these general instructions you should also set the following environment variables PATH lt JWSDP_HOME gt apache ant bin PATH ANT_HOME lt JWSDP_HOME gt apache ant CLASSPATH lt JWSDP_HOME gt sjsxp 1ib CLASSPATH 109 110 STREAMING API FOR XML Running the Samples The samples can be run either manually or by means of several Ant targets defined in the lt JWSDP_HOME gt sjsxp samples build xml1 file It is easiest to run the samples using the Ant targets When you run any of the samples the compiled class files are placed in a direc tory named build This directory is created if it does not exist already Running the Samples Using Ant Use the Ant build file bui1d xm1 in the lt JWSDP_HOME gt sjsxp samples direc tory to run the SJSXP samples There are eight targets defined in SJSXP build xml file all Compile and run all classes default target compile Only compile classes do not run cursor CursorParse Compile and run cursor CursorParse java cursor2event CursorApproachEventObject Compile and run cursor2event CursorApproachEventObject java event EventParse Compile and run event EventParse java filter MyStreamFilter Compile and run filter MyStreamFil ter jav
319. lease of XWS Security FCS 2 0 257 258 UNDERSTANDING AND RUNNING THE XWS SECURITY SAMPLE APPLICATIONS The full code for the SecurityEnvironmentHandler is located in the dynamic policy src com sun xml wss sample directory The SecurityEn vironmentHandler file is a sample implementation of a Cal lbackHandler The following snippet of that file demonstrates how to handle a DynamicPolicy Callback else if Ccallbacks i instanceof DynamicPolicyCallback DynamicPolicyCallback dpCallback DynamicPolicyCallback callbacks i SecurityPolicy policy dpCallback getSecurityPolicy if policy instanceof WSSPolicy try handleWSSPolicy dpCallback catch PolicyGenerationException pge throw new IOException pge getMessage else if policy instanceof DynamicSecurityPolicy try handleDynamicSecurityPolicy dpCallback catch PolicyGenerationException pge throw new IOException pge getMessage else throw unsupported Running the Dynamic Policy Sample Applicaton To run the dynamic policy sample application follow these steps 1 Complete the tasks defined in the following sections of this addendum Setting System Properties Configuring a JCE Provider Setting Build Properties 2 Start the selected container and make sure the server is running To start the Application Server a From a Unix machine enter the following command from a terminal window asadmin start domain do
320. led ClassificationNodes in the ebXML specifi cations The primary purpose of the canonical classification schemes is not to classify objects but to provide enumerated types for object attributes For exam 17 18 DEVELOPING CLIENTS FOR THE SERVICE REGISTRY ple the EmailType classification scheme provides a set of values for the type attribute of an EmailAddress object Table 8 4 lists and describes these canonical classification schemes Table 8 4 Canonical Classification Schemes AssociationType Defines the types of associations between RegistryObjects ContentManagementSer vice Defines the types of content management services DataType Defines the data types for attributes in classes defined by the specification DeletionScopeType Defines the values for the de etionScope attribute in the RemoveObjectsRequest protocol message Emai lType Defines the types of email addresses ErrorHandlingMode1 Defines the types of error handling models for content manage ment services ErrorSeverityType Defines the different error severity types encountered bythe registry during processing of protocol messages EventType Defines the types of events that can occur in a registry InvocationModel Defines the different ways that a content management service may be invoked by the registry NodeType Defines the different ways in which a Classification Scheme may assign the valu
321. lied to the object to be encrypted Transform 168 INTRODUCTION TO XML AND WEB SERVICES SECURITY Symmetric Key The lt Symmetrickey gt element indicates the symmetric key to be used for encryption This element must not be specified if the lt x509Token gt or lt SAMLAs sertion gt sub elements are present Its attributes are discussed in Table 4 35 Table 4 35 Attributes of SymmetricKey Attributes of SymmetricKey Description keyklias The alias of the symmetric key to be used for encryption This attribute is required CanonicalizatonMethod The lt CanonicalizationMethod gt element specifies the canonicalization algo rithm to be applied to the lt SignedInfo gt element prior to performing signature calculations When specified the canonical XML XML C14N standard which is an algorithm that standardizes the way XML documents should be ordered and structured should be applied The recommendation that discusses this method is the W3C XML Signature Syntax and Processing recommendation which can be viewed at http www w3 org TR xmldsig core sec CanonicalizationMethod Its attributes are discussed in Table 4 36 Table 4 36 Attributes of CanonicalizationMethod Attributes of CanonicalizationMethod Description The algorithm to be used for signing There is no default value You must explicitly add http www w3 org 2001 10 xml exc c14n to the transforms list in the configuration file if you want to use i
322. lient xml and sign server xm1 enable the following tasks e Client signs the request body e Server verifies the signature and sends its response The sign client xm file looks like this lt xwss JAXRPCSecurity xmIns xwss http java sun com xml ns xwss config gt lt xwss Service gt SIMPLE SAMPLE SECURITY CONFIGURATION FILES 215 lt xwss SecurityConfiguration dumpMessages true gt lt Note that in the lt Sign gt operation a Timestamp is exported in the security header and signed by default gt lt xwss Sign gt lt xwss X509Token certificateAlias xws security client gt lt xwss Sign gt lt Signature requirement No target is specified hence the soap body is expected to be signed Also by default a Timestamp is expected to be signed gt lt xwss RequireSignature gt lt xwss SecurityConfiguration gt lt xwss Service gt lt xwss SecurityEnvironmentHandler gt sample SecurityEnvironmentHandler lt xwss SecurityEnvi ronmentHand1er gt lt xwss JAXRPCSecurity gt Signing then Encrypting the Request Dec rypting then Venfying the Signature The security configuration pair sign encrypt client xml and sign encrypt server xml enable the following tasks e Client signs and then encrypts and sends the request body e Server decrypts and verifies the signature e Server signs and then encrypts and sends the response The sign encrypt client xm1 file looks like this
323. 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 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 cl
324. lisions 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 xml file and then run ant in the lt JWSDP_HOME gt jaxb samples fix collides directory the customizations in 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 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 JWSDP_HOME gt jaxb samples 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 Q gt lt xs element name FooBar gt lt xs
325. ll 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 Ant with the build xm1 project file included in each example directory Configuring and Running the Samples The build xm1 file included in each example directory is an Ant project file that when run automatically performs the following steps 1 Updates your CLASSPATH to include the necessary schema derived JAXB classes 2 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 3 Generates API documentation from the schema derived JAXB classes using the Javadoc tool CONFIGURING AND RUNNING THE SAMPLES 4 Compiles the schema derived JAXB classes 5 Runs the Main class for the example Solanis Linux 1 Set the following environment variables export JAVA_HOME lt your J2SE installation directory gt export JWSDP_HOME lt your JWSDP installation directory gt 2 Change to the desired example directory For example to run the Unmarshal Read example cd lt JWSDP_HOME gt jaxb samples unmarshal read lt JWSDP_HOME gt is the directory where you installed the Java WSDP bun dle 3 Run ant JWSDP_HOME ap
326. lt Secondly sign the soap body using some default private key The sample CallbackHandler implementation has code to handle SIMPLE SAMPLE SECURITY CONFIGURATION FILES 217 the default signature private key request gt lt xwss Sign gt lt xwss SecurityConfiguration gt lt xwss Service gt lt xwss SecurityEnvironmentHandler gt sample SecurityEnvironmentHandler lt xwss SecurityEnvi ronmentHand1er gt lt xwss JAXRPCSecurity gt Signing a Ticket The security configuration pair sign ticket also client xml and sign ticket also server xm1 enable the following tasks e Client signs the ticket element which is inside the message body e Client signs the message body e Server verifies signatures The sign ticket also client xml file looks like this lt xwss JAXRPCSecurity xmIns xwss http java sun com xml ns xwss config gt lt xwss Service gt lt xwss SecurityConfiguration dumpMessages true gt lt Signing multiple targets as part of the same ds Signature element in the security header gt lt xwss Sign gt lt xwssS Target type qname gt http xmlsoap org Ping ticket lt xwss Target gt lt xwss Target type xpath gt env Body lt xwss Target gt lt xwss Sign gt lt xwss SecurityConfiguration gt lt xwss Service gt lt xwss SecurityEnvironmentHandler gt sample SecurityEnvironmentHandler lt xwss SecurityEnvi ronmentHand1er gt lt xwss JAXRPCSecurity g
327. lt xwss Target type uri gt username token lt SIMPLE SAMPLE SECURITY CONFIGURATION FILES xwss Target gt lt xwss Encrypt gt lt xwss SecurityConfiguration gt lt xwss Service gt lt xwss SecurityEnvironmentHandler gt sample SecurityEnvironmentHandler lt xwss SecurityEnvi ronmentHand1er gt lt xwss JAXRPCSecurity gt In this sample the UsernameToken is assigned an id username token This id is used to refer to the token as an encryption target within the lt xwss Encrypt gt ele ment The id becomes the actual wsu id of the UsernameToken in the generated SOAPMessage Adding a UserName Password Token then Encrypting the UserName Token The security configuration pair encrypted user pass client xm and encrypted user pass server xm enable the following tasks e Client adds a UsernameToken e Client encrypts the UsernameToken before sending the request e Server decrypts the UsernameToken e Server authenticates the user name and password against a username pass word database The encrypted user pass client xml file looks like this lt xwss JAXRPCSecurity xmIns xwss http java sun com xml ns xwss config gt lt xwss Service gt lt xwss SecurityConfiguration dumpMessages true gt lt xwss UsernameToken name Ron password noR gt lt xwss Encrypt gt lt xwss X509Token certificateAlias slas keyReferenceType Identifier gt lt xwss Target type qname gt http docs oasis open org
328. ma xmlns http java sun com xml ns xwss config targetNamespace http java sun com xml ns xwss config elementFormDefault qualified gt lt xs element name JAXRPCSecurity gt lt xs complexType gt lt xs sequence gt lt xs element name Service type Service_T minOccurs 0 maxOccurs unbounded gt lt xs element name SecurityEnvironmentHandler type xs string gt 103 104 A XWS SECURITY FORMAL SCHEMA DEFINITION lt xs sequence gt lt xs complexType gt lt xs element gt lt xs complexType name Service_T gt lt xs sequence gt lt xs element ref SecurityConfiguration minOccurs 0 gt lt xs element name Port type Port_T minOccurs 0 maxOccurs unbounded gt lt xs element name SecurityEnvironmentHandler type xs string minOccurs 0 gt lt xs sequence gt lt xs attribute name name type xs string use optional gt lt xs attribute name id type id_T use optional gt lt xs attribute name conformance use optional gt lt xs simpleType gt lt xs restriction base xs string gt lt xs enumeration value bsp gt lt xs restriction gt lt xs simpleType gt lt xs attribute gt lt xs attribute name useCache type xs boolean use optional default false gt lt xs complexType gt lt xs complexType name Port_T mixed true gt lt xs sequence gt lt xs element ref SecurityConfiguration minOccurs 0 gt lt xs element name Operation type Operation_T minOc
329. ma Q edited by David C Fallside 25 26 USING JAXB General Usage Instructions This section provides general usage 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 ten examples the basic examples Unmarshal Read Modify Marshal Create Marshal Unmarshal Validate Validate On Demand demonstrate basic JAXB concepts like ummarshalling marshalling and validat ing XML content while the customize examples Customize Inline Datatype Converter External Customize Fix Collides Bind Choice demonstrate various ways of customizing the binding of XML schemas to Java objects Each of the examples in this chapter is based on a Purchase Order scenario With the excep tion of the Bind Choice and the Fix Collides examples each uses an XML docu ment po xm1 written against an XML schema po xsd Table 2 1 Sample JAXB Application Descriptions 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 Demonstrates how to use the ObjectFactory class to create a Create Marshal Exaniple Java content tree from scratch and then marshal it to XML data Unmarshal Validate Demon
330. main1 RUNNING THE DYNAMIC POLICY SAMPLE APPLICATION 259 b From a Windows machine choose Start Programs Sun Microsystems J2EE 1 4 Start Default Server 3 Build and run the application from a terminal window or command prompt e On the Application Server the command to build and run the applica tion is asant run sample e On the other containers the command to build and run the application is ant run sample Note To run the sample against a remote server containing the deployed endpoint use the run remote samp e target in place of the run samp1e target In this situa tion make sure that the endpoint host endpoint port http proxyHost http proxyPort and service url properties are set correctly in the build prop erties file as discussed in Setting Build Properties before running the sample If the application runs successfully you will see a message similar to the follow ing echo Running the client program java Sending Message Start java Sending Message End java Received Message Start java Received Message End You can view similar messages in the server logs lt SJSAS_HOME gt domains lt domain name gt logs server log lt TOMCAT_HOME gt logs launcher server log lt SJISWS_HOME gt lt Virtual Server Dir gt logs errors 260 UNDERSTANDING AND RUNNING THE XWS SECURITY SAMPLE APPLICATIONS Dynamic Response Sample Application The dyna
331. ment For example suppose you declared two namespaces in your schema one for foo and another for bar Two XML docu ments are combined one from a billing database and another from an shipping database each of which was written against a different schema By specifying REPRESENTING XML CONTENT namespaces in your schema you can differentiate between say foo address and bar address Representing XML Content This section describes how JAXB represents XML content as Java objects Spe cifically the topics in this section are as follows e Binding XML Names to Java Identifiers e Java Representation of XML Schema Binding XML Names to J ava Identifiers XML schema languages use XML names strings that match the Name produc tion defined in XML 1 0 Second Edition http www w3 org XML to label schema components This set of strings is much larger than the set of valid Java class method and constant identifiers To resolve this discrepancy JAXB uses several name mapping algorithms The JAXB name mapping algorithm maps XML names to Java identifiers in a way that adheres to standard Java API design guidelines generates identifiers that retain obvious connections to the corresponding schema and is unlikely to result in many collisions Refer to Chapter 2 for information about changing default XML name map pings See Appendix C in the JAXB Specification for complete details about the JAXB naming algorithm Java Representation
332. mentations of the runtime binding framework APIs contained in the javax xm1 bind package For instructions on using the JAXB see Chapter 2 23 24 BINDING XML SCHEMA TO JAVA CLASSES WITH JAXB 2 Using J AXB Tiss chapter provides instructions for using several of the sample Java appli cations that were included in the Java WSDP These examples demonstrate and build upon key JAXB features and concepts It is recommended 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 54 for instructions on using five additional examples that demonstrate how to modify the default JAXB bindings Note The Purchase Order schema po xsd and the Purchase Order XML file po xml used in these samples are derived from the W3C XML Schema Part 0 Primer http www w3 org TR xm 1sche
333. mic response sample application demonstrates using the certificate that arrived in a signed request to encrypt the response back to the requester using the XWS Security APIs To accomplish this task e ACallbackHandler retrieves the requester Subject and obtains its certif icate e The requester certificate is used to encrypt the response back to the requester The application prints out both the client and server request and response SOAP messages The output from the server may be viewed in the appropriate con tainer s log file The output from the client is sent to stdout or to whichever stream is used by the configured log handler Messages are logged at the INFO level In this example server side code is found in the dynamic response server src sample directory Client side code is found in the dynamic response client src sample directory The asant or ant targets build objects under the build server and build client directories Security Configuration Flies for Enabling Dynamic Response For this sample application the security configuration files are fairly simple The security configuration files are used to sign the request and encrypt the response but the work of using the requester certificate to encrypt the response back to the requester is accomplished using the SecurityEnvironmentHandler which is discussed in Using the CallbackHandler to Enable Dynamic Response The client security configuration file for this
334. mizations 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 CDATAL Contents in lt b gt Javadoc lt b gt format gt lt javadoc gt 67 68 USING JAXB 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 Customization 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 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 declar
335. mple 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 JWSDP_HOME gt jaxb samples 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 import javax xml bind Unmarshal ler import primer po A JAXBContext instance is created for handling classes generated 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 44 USING JAXB 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
336. mpleType gt lt xs restriction base xs string gt lt xs enumeration value http www w3 org 2001 04 xmlenc aes 128 cbe gt lt xs enumeration value http www w3 org 2001 04 xmlenc aes256 cbe gt lt xs enumeration value http www w3 org 2001 04 xmlenc tripledes cbc gt lt xs restriction gt lt xs simpleType gt lt xs attribute gt lt xs complexType gt lt xs complexType name EncryptionTarget_T gt lt xs sequence gt lt xs element name Transform type Transform_T minOccurs 0 maxOccurs unbounded gt lt xs sequence gt lt xs attribute name type type xs string use optional default qname gt lt xs attribute name contentOnly type xs boolean use optional default true gt lt xs attribute name enforce type xs boolean use optional default true gt lt xs attribute name value type xs string use required gt lt xs complexType gt lt xs complexType name SymmetricKey_T gt lt xs attribute name keyAlias use required gt lt xs simpleType gt lt xs restriction base xs string gt lt xs minLength value 1 gt lt xs restriction gt FORMAL SCHEMA DEFINITION 109 lt xs simpleType gt lt xs attribute gt lt xs complexType gt lt xs complexType name Sign_T gt lt xs sequence gt lt xs choice minOccurs 0 maxOccurs 1 gt lt xs element name X509Token type X509Token_T gt lt xs element name SAMLAssertion type SAMLAssertion_T
337. n about commands Synopsis help command_name Description The help command displays information about the available commands or a specified command For commands with subcommands such as add and show the help command displays information about the subcommands If you do not specify an argument the help command displays usage informa tion for all commands Operand command_name The name of an Admin Tool command Examples The following command displays usage information for all commands admin gt help The following command displays usage information for the 1cd command admin gt help lcd The following command displays usage information for the add subcommands admin gt help add 92 ADMINISTERING THE SERVICE REGISTRY Icd Changes the current directory on the local file system Synopsis lcd path_name Desc nption The 1cd command changes the current local directory on the local file system If you do not specify an argument the 1cd command changes the current direc tory to your default home directory Operand path_name A directory name which may be absolute or relative Examples The following command changes the current local directory to the usr share directory admin gt cd usr share The following command changes the current local directory to your default home directory on the local file system admin gt lcd Is Lists the objects in the current RegistryPackage LS
338. n defaults to user home keystore storepass store Password of the keystore User is prompted for the password if password this option is omitted The password used to protect the private key inside the key store User is prompted for the password if this option is omit ted keypass key pass word alias alias The alias of the key entry inside the keystore 200 INTRODUCTION TO XML AND WEB SERVICES SECURITY wscompi le The wscompi le tool generates the client stubs and server side ties for the service definition interface that represents the Web service interface Additionally it generates the WSDL description of the Web service interface which is then used to generate the implementation artifacts XWS Security has been integrated into JAX RPC through the use of security configuration files The code for performing the security operations on the client and server is generated by supplying the configuration files to the JAX RPC wscompi le tool The wscompi1e tool can be instructed to generate security code by making us of the security option to specify the location of the security configuration file that contains information on how to secure the messages to be sent An example of using the security option with wscompile is shown in How Do I Specify the Security Configuration for the Build Files Note For the 2 0 release of JAX RPC JAX RPC will be renamed to JAX WS JAX WS will become part of the X
339. n external binding customization file enables you to customize JAXB 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 CUSTOMIZATION OVERVIEW Inline Customizations Customizations to JAXB bindings made by means of inline binding 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 xs annotation 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
340. n the command line or in a properties file mn middleName Specifies the middle name of a user alias The alias to use when accessing the user s certificate in the keystore keypass The password to use when accessing a user s certificate in the keystore postalType postl type ADD USER The type of the first PostalAddress The type is required it must be specified either on the command line or in a properties file It is an arbi trary string for example Of fice or Home city postl city The city of the first PostalAddress country post1 country The country of the first PostalAddress postalcode postcode zip post1 postalcode The postal code of the first PostalAddress stateOrProvince state province post1 stateOrProvince The state or province of the first PostalAddress street postl street The street name of the first PostalAddress The street is required it must be specified either on the command line or in a properties file streetNumber number post1 streetNumber The street number of the first PostalAddress post2 type The type of the second PostalAddress If a second PostalAddress is specified the type is required it must be specified either on the command line or in a properties file It is an arbitrary string for example Of fice or Home post2 city The city of the second PostalAddress post2 country 81 82 ADMINISTERING THE SERVICE REGISTRY The coun
341. n to creating and sav ing all registry objects They then describe some tasks specific to particular object types Adding names and descriptions to objects Identifying objects Adding classifications to objects Adding external identifiers to objects Adding external links to objects Adding slots to objects Creating organizations Creating users Creating services and service bindings Using Create Methods for Objects Adding Names and Descriptions to Objects Identifying Objects Creating and Using Classification Schemes and Concepts Adding Classifications to Objects Adding External Identifiers to Objects Adding External Links to Objects Adding Slots to Objects Creating Organizations Creating Users Creating Services and Service Bindings 44 DEVELOPING CLIENTS FOR THE SERVICE REGISTRY Using Create Methods for Objects The LifeCycleManager interface supports create methods for all types of Reg istryObject except AuditableEvent and Notification which can be cre ated only by the Registry itself In addition you can use the LifeCycleManager createObject factory method to create an object of a particular type This method takes a String argument con sisting of one of the static fields supported by the LifeCycleManager interface In the following code fragment b1cm is the BusinessLifeCycleManager object Organization org Organization blcm createObject b1cm ORGANIZATION The object specific create methods usu
342. nager unDepre cateObjects method The LifeCycleManagerImp1 approveObjects method has the following signa ture public BulkResponse approveObjects java util Collection keys throws JAXRException It is possible to restrict access to these actions to specific users such as registry administrators No Audi tableEvent is created for actions that do not alter the state of a Regis tryObject For example queries do not generate an AuditableEvent and no AuditableEvent is generated for a RegistryObject when it is added to a Reg istryPackage or when you create an Association with the object as the source or target Changing the State of Objects in the Registry Examples For examples of approving deprecating undeprecating objects see the exam ples in lt INSTALL gt registry samples auditable events src JAXRAp proveObject java JAXRDeprecateObject java and JAXRUndeprecateObject java Each example performs an action on an object whose unique identifier you specify then displays the object s audit trail so that you can see the effect of the example To run the examples follow these steps 1 Go to the directory lt INSTALL gt registry samples packages 2 Type the following command ant approve obj Did id_string 3 Type the following command ant deprecate obj Did id_string 4 Type the following command REMOVING OBJECTS FROM THE REGISTRY AND REPOSITORY 67 ant undeprecate obj Did id_string The object you specify shou
343. ncludeTimestamp false gt lt xwss UsernameToken name Ron password noR useNonce true digestPassword false gt lt xwss Timestamp timeout 300 gt lt xwss SecurityConfiguration gt lt xwss Service gt lt xwss SecurityEnvironmentHandler gt SIMPLE SAMPLE SECURITY CONFIGURATION FILES sample SecurityEnvironmentHandler lt xwss SecurityEnvironmentHand1ler gt lt xwss JAXRPCSecurity gt Adding Securty at the Method Level The security configuration pair method level client xml1 and method level server xml enable the following tasks e Configures different security policies for different WSDL methods of the application and different port instances The simple sample s WSDL file contains two operations Ping and Ping and two port instances of type PingPort The port names are Ping and Ping The method level security configuration file demonstrates how different sets of secu rity operations can be configured for the operations Ping and Ping under each of the two Port instances Ping and Ping The method level client xm1 file looks like this lt xwss JAXRPCSecurity xmIns xwss http java sun com xml ns xwss config gt lt xwss Service gt lt Service level security configuration gt lt xwss SecurityConfiguration dumpMessages true gt lt xwss Encrypt gt lt xwss X509Token certificateAlias slas gt lt xwss Encrypt gt lt xwss SecurityConfiguration gt lt xwss Port name
344. nd 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 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 plugg
345. nd indenta tion A true value for this property indicates human readable indented XML data while a false value indicates unformatted XML data The Marshal ler defaults to false unformatted if this property is not specified jaxb schemaLocation Value must be a java lang String allows the client application to specify an xsi schemaLoca tion attribute in the generated XML data The for mat of the schemaLocation attribute value is discussed in an easy to understand non normative form in Section 5 6 of the W3C XML Schema Part 0 Primer and specified in Section 2 6 of the W3C XML Schema Part 1 Structures jaxb noNamespaceSchemaLocation Value must be a java lang String allows the client application to specify an xsi noNamespac eSchemaLocation attribute in the generated XML data More About Validation The Validator class in the javax xm1 bind package is responsible for control ling the validation of content trees during runtime When the unmarshalling pro cess incorporates validation and it successfully completes without any validation errors both the input document and the resulting content tree are guaranteed to be valid By contrast the marshalling process does not actually perform valida tion If only validated content trees are marshalled this guarantees that generated XML documents are always valid with respect to the source schema 11 12 BINDING XML SCHEMA TO JAVA CLASSES WITH JAXB Some XML parsers
346. nding files on the com mand line does not matter d lt dir gt By default xjc will generate Java content classes in the current directory Use this option to specify an alternate output directory The directory must already exist xjc will not create it for you p lt pkg gt Specifies the target package for schema derived classes This option overrides any binding customization for package name as well as the default package name algorithm defined in the JAXB Specifica tion host lt proxyHost gt Set http proxyHost to lt proxyHost gt port lt proxyPort gt Set http proxyPort to lt proxyPort gt classpath lt arg gt Specify where to find client application class files used by the lt jxb javaType gt and lt xjc superClass gt customizations catalog lt file gt Specify catalog files to resolve external entity references Supports TR9401 XCatalog and OASIS XML Catalog format readOnly Generated source files will be marked read only By default xjc does not write protect the schema derived source files it generates use runtime lt pkg gt Suppress the generation of the imp runtime package and refer to another existing runtime in the specified package This option is useful when you are compiling multiple independent schemas Because the generated impl runtime packages are identical except for their package declarations you can reduce the size of your gen erated
347. ndow opens Expand the ClassificationSchemes node then expand concept nodes until you have selected the leaf node you want to use Click OK to close the ClassificationScheme Concept Selector window The classification scheme and concept appear in the Details Panel win dow Click Add to close the Details Panel window The new version of the object appears in the Registry Objects area Click Save in the Details area for the object Adding an Extemal Link to an Object An external link allows you to associate a URI with a registry object To add an external link to an object follow these steps 1 In the Details area for the object click the ExternalLinks tab The ExternalLinks table which may be empty appears 2 Click Add A Details Panel window opens ADDING CUSTOM INFORMATION TO AN OBJECT USING SLOTS 297 3 Type a name for the external link 4 Type the URL for the external link in the External URI field 5 Optionally click the Select Concept for Object Type button if you want to specify the type of content to which the URL points Expand the ClassificationSchemes node and locate the content type by expanding the ObjectType RegistryObject and ExtrinsicObject nodes Select the concept then click OK If you do not find a suitable type click Cancel You can create a new concept for ExtrinsicObjects if you wish 6 Click Add to close the Details Panel window The new version of the object appea
348. nfig gt lt xwss Encrypt gt lt xwss X509Token certificateAlias slas gt lt xwss KeyEncryptionMethod algorithm http www w3 org 2001 04 xml enc rsa oaep mgflp gt lt xwss DataEncryptionMethod algorithm http www w3 org 2001 04 xmlenc aes128 cbc gt lt xwss EncryptionTarget type xpath value SOAP ENV Body gt lt xwss Encrypt gt lt xwss SecurityConfiguration gt Signing the SOAP Message The security configuration files signv1 xml signv2 xml1 and signv3 xm enable the following tasks e Client signs an outbound SOAPMessage and sends it e Client verifies that the inbound SOAPMessage is signed 238 UNDERSTANDING AND RUNNING THE XWS SECURITY SAMPLE APPLICATIONS The signvi1 xm1 file looks like this lt xwss SecurityConfiguration dumpMessages true xmIns xwss http java sun com xml ns xwss config gt lt Note that in the lt Sign gt operation a Timestamp is exported in the security header and signed by default gt lt xwss Sign gt lt xwss X509Token certificateAlias xws security client gt lt xwss Sign gt lt xwss SecurityConfiguration gt The signv2 xm1 file does the same thing except that it also includes the follow ing e Specifies the canonicalization algorithm to be applied to the lt Sign gt ele ment prior to performing signature calculations e Specifies the algorithm used for signature generation and validation e Provides a list of processing ste
349. nfomodel interfaces An optional interface DeclarativeQuery Manager allows the client to use SQL syntax for queries The ebXML provider for the Registry implements DeclarativeQueryManager e LifeCycleManager and BusinessLifeCycleManager which allow the client to modify the information in a registry by either saving it updating it or deleting it 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 8 1 illustrates the architecture of JAXR For the Registry a JAXR client uses the capability level 0 and level 1 interfaces of the JAXR API to access the JAXR provider which is an ebXML provider The JAXR provider in turn accesses the Registry an ebXML registry JAAR AFI Capabilihy Specie interlaces eo Aegisiry Specific JAXA Provicher ER Provider LUDO Prenidar Oihar Pelee Diverse Ragisirias SHEN Woo Figure 8 1 JAXR Architecture ABOUT THE EXAMPLES About the Examples Many sample client programs that demonstrate JAXR features are available as part of the Java Web Services Developer Pack Java WSDP If you install the Java WSDP you will find them in the directory lt INSTALL gt registry samples lt INSTALL gt is the directory where you installed the Java WSDP Each example or group of examples has
350. ng Rules Summary See the JAXB Specification for complete information 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 DEFAULT DATA TYPE BINDINGS 19 e Predicate The rest of the Java property attributes are specified in the schema component using the simple type definition Default Data Type Bindings The Java language provides a richer set of data type than XML schema Table 1 3 lists the mapping of XML data types to Java data types in JAXB Table 1 3 JAXB Mapping of XML Schema Built in Data Types XML Schema Type Java Data Type rstring java lang String integer java math BigInteger tint int long long short short decimal java math BigDecimal float float double double boolean boolean byte byte QName javax xml namespace QName dateTime java util Calendar base64Binary byte hexBinary byte unsignedInt long unsignedShort int unsignedByte short 20 BINDING XML SCHEMA TO JAVA CLASSES WITH JAXB Table 1 3 JAXB Mapping of XML Schema Built in Data Types Continued XML Schema Type Java Data Type xsd time java util Calendar xsd date java ut
351. ni parser XMLDocumentSource class com sun xm1 stream xerces xni parser XMLEntityResolver class com sun xml stream xerces xni parser XMLErrorHandler class com sun xm1 stream xerces xni parser XMLInputSource class com sun xml1 stream xerces xni parser XMLParseException class com sun xml stream xerces xni parser XMLParserConfiguration cl ass com sun xml stream xerces xni parser XMLPul 1ParserConfiguratio n class ja173 _apijar The jsr173_api jar file contains the following files META INF pack properties javax xm1 XMLConstants class javax xml namespace NamespaceContext class javax xml namespace QName class javax xml stream EventFilter class javax xml1 stream FactoryConfigurationError class javax xml stream FactoryFinder class 120 SJSXP JAR FILES javax xml stream FactoryFinder 1 class javax xml1 stream FactoryFinder ClassLoaderFinder class javax xml stream FactoryFinder ClassLoaderFinderConcrete class javax xml stream Location class javax xml stream StreamFilter class javax xml1 stream XMLEventFactory class javax xml stream XMLEventReader class javax xml stream XMLEventWriter class javax xml stream XMLInputFactory class javax xml stream XMLOutputFactory class javax xml stream XMLReporter class javax xml stream XMLResolver class javax xml stream XMLStreamConstants class javax xml stream XMLStreamException class javax xml stream XMLStreamReader class javax xml stream XMLStreamWriter class javax xml stream events Attribute class javax
352. ning data that is constrained by an XML schema is referred to as a document instance and the structure and data within a document instance is referred to as a content tree 13 14 BINDING XML SCHEMA TO JAVA CLASSES WITH JAXB Note In practice the term document is not always accurate as an XML instance document does not have to be a completely formed selfstanding document file it can instead take the form of streams of data passed between applications or of sets of database fields or of XML infosets in which blocks of information contain just enough information to describe where they fit in the schema structure The following sample code is taken from the W3C s Schema Part 0 Primer http www w3 org TR 2001 REC xm1schema 0 20010502 and illustrates an XML document po xm1 for a simple purchase order lt xml version 1 0 gt lt purchaseOrder orderDate 1999 10 20 gt lt shiplo country US gt lt name gt Alice Smith lt name gt lt street gt 123 Maple Street lt street gt lt city gt Mill Valley lt city gt lt state gt CA lt state gt lt Zip gt 90952 lt zip gt lt shipTo gt lt bil1To country US gt lt name gt Robert Smith lt name gt lt street gt 8 Oak Avenue lt street gt lt city gt Old Town lt city gt lt state gt PA lt state gt lt Zip gt 95819 lt zip gt lt bil1To gt lt comment gt Hurry my lawn is going wild lt comment gt lt items gt lt item partNum 872 AA gt lt
353. ning the query The following code fragment creates an SQL query 36 DEVELOPING CLIENTS FOR THE SERVICE REGISTRY that asks for a list of all Service objects in the Registry Here rs is a Registry Service object DeclarativeQueryManager qm rs getDeclarativeQueryManager String qString select s from Service s Query query qm createQuery Query QUERY_TYPE_SQL qString After you create the query you execute it as follows BulkResponse response qm executeQuery query Collection objects response getCollection You then extract the objects from the response just as you do with ordinary que ries Using Declarative Queres Example For an example of the use of declarative queries see lt INSTALL gt registry samples query declarative src JAXRQueryDeclarative java which cre ates and executes a SQL query The SQL query string which is defined in the JAXRExamples properties file looks like this all on one line declarative query SELECT ro from RegistryObject ro Name nm Description d WHERE upper nm value LIKE upper free AND upper d value LIKE upper free AND ro id nm parent AND ro id d parent This query finds all objects that have the string free in both the name and the description attributes To run the example follow these steps 1 Go to the directory lt INSTALL gt registry samples query declara tive 2 Type the following command ant run Using Iterative
354. nnotations in a source XML schema e As declarations in an external binding customizations file that is passed to the JAXB binding compiler 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 You do not need to provide a binding instruction for every declaration in your schema to generate Java classes For example the binding compiler uses a gen eral name mapping algorithm to bind XML names to names that are acceptable in the Java programming language However if you want to use a different nam ing scheme for your classes you can specify custom binding declarations to make the binding compiler generate different names There are many other cus tomizations you can make with the binding declaration including e Name the package derived classes and methods e Assign types to the methods within the derived classes e Choose which elements to bind to classes e Decide how to bind each attribute and element declaration to a property in the appropriate content class e Choose the type of each attribute value or content specification Note Relying on the default JAXB binding behavior rather than requiring a binding declaration for each XML Schema component bound to a Java representation makes it easier to keep pace with changes in the source schema In most cases the default
355. ns 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 ebXML stands for Electronic Business using eXtensible Markup Language e The Universal Description Discovery and Integration UDDI project which is developed by a vendor consortium A registry provider is an implementation of a registry that conforms to a specifi cation for XML registries While a UDDI registry stores information about businesses and the services they offer an ebXML registry has a much wider scope It is a repository as well as a registry A repository stores arbitrary content as well as information about that content In other words a repository stores data as well as metadata The ebXML Registry standard defines an interoperable Enterprise Content Management ECM API for web services An ebXML registry and repository is to the web what a relational database is to enterprise applications it provides a means for web services and web applica tions to store and share content and metadata An ebXML registry can be part of a registry federation an affiliated group of registries For example the health ministry of a country in Europe could operate a registry and that registry could be part of a federat
356. nt writer flushQ 124 STREAMING API FOR XML Creating a Whiter 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 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 FURTHER INFORMATION 125 Further Information For more information about StAX see Java Community Process page http jcp org en jsr detai1l id 17
357. nt contains an xwss X509Token child with no certificateAlias attribute set on it XWS Security tries to obtain a default certificate from the Callback to be used for encrypting the random sym metric key 3 When the xwss Encrypt element contains an xwss SymmetricKey child specifying the keyAlias attribute This alias indicates that a symmetric key corre sponding to this alias needs to be located and used for encryption of the specified message part 4 When an X 509 certificate needs to be obtained for a given public key Request Inner Classes Defined The following are the Request inner classes with which an EncryptionKey Callback can be ini tialized 1 AliasxX509Certi fi cateRequest A Callback initialized with this request should be handled if the X 509 certificate to be used for encryp tion is mapped to an alias D DefaultX509Certi ficateRequest A Callback initialized with this request should be handled if there s a default X 509 certificate to be used for encryption 3 AliasSymmet ricKeyRequest A Callback initialized with this request should be handled if the symmetric key to be used for encryp tion is mapped to an alias 4 PublicKeyBase dRequest Request for an X 509 certifi cate for a given public key Methods in the Request Classes The following two methods are present in the AliasxX509CertificateRequ est and Defaultx509CertificateRe quest Request classes of th
358. nt for stand alone SAAJ applications is lt SecurityConfiguration gt Table 4 3 provides a description of the sub elements of lt JAXRPCSecurity gt Table 4 3 Sub elements of JAXRPCSecurity element Sub elements of JAXRPCSecurity Description Indicates a JAX RPC service within the XWS Security environment for which XWS Security can be configured In this release multiple services per configuration file are supported Service Specifies the implementation class name of the security a aaa environment handler Required Service The lt Service gt element indicates a JAX RPC service within the XWS Security environment for which XWS Security can be configured 146 INTRODUCTION TO XML AND WEB SERVICES SECURITY Note Although the XWS Security configuration schema allows multiple lt Ser vice gt elements to appear under a lt JAXRPCSecurity gt element the current release does not support this feature The configuration reader will throw an Illegal StateException if multiple services are specified Table 44 provides a descrip its sub elements tion of its attributes Table 4 5 provides a description of Table 4 4 Attributes of Service element The name of the JAX RPC service optional Attributes of Service id The id of the JAX RPC service optional conformance Type of conformance In this release the choice for this attribute is restricted to bsp optional useCache Dete
359. ntQ printAttributes xmlr printPIDataCxmlr System out printIn ee Capturing the Event Steam The next step is to capture the event stream This is done in basically the same way as in the 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 isEndElementQ return false else return true 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 122 STREAMING API FOR XML 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 INR 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 EventProduc erC onsumerjava Located in the lt JWSDP_HOME gt sjsxp samples readnwrite directory EventPro ducerConsumer java demonstrates how to use a StAX parser simultaneo
360. ntact name pcName getFirstName pcName getMiddleName pcName getLastName To retrieve the email addresses for a user call the User getEmai1lAddresses method An EmailAddress has two attributes the address and its type In the fol lowing code fragment pc is the primary contact Collection eAddrs pc getEmailAddresses Iterator eaIter eAddrs iteratorQ while CeaIter hasNext EmailAddress eAd EmailAddress eaIter next Q System out printIn Email address eAd getAddress eAd getTypeQ The attributes for PostalAddress TelephoneNumber PersonName and Email Address objects are all String values As noted in JAXR Information Model Interfaces page 11 these objects do not extend the RegistryObject interface so they do not have the attributes of other registry objects Retrieving Organization Attributes Example For an example of retrieving the attributes of an organization and the User that is its primary contact see the example lt INSTALL gt registry samples organi zations src JAXRQueryOrg java which displays information about an orga nization whose name contains a specified string To run the example follow these steps 1 Go to the directory lt INSTALL gt registry samples organizations 2 Type the following command ant query org Dorg string RETRIEVING INFORMATION ABOUT AN OBJECT Retrieving the Services and Service Bindings for an Organization Mo
361. nterface 30 getAreaCode method Telephone Number interface 29 getAuditTrail method Registry Object interface 33 GetCallersUser stored query 38 getChildOrganizations method Organization interface 32 getCity method PostalAddress interface 29 getClassifications method Reg istryObject interface 26 getConnectionFactory method 8 getCountry method PostalAd dress interface 29 getCountryCode method Tele phoneNumber interface 29 getDescendantOrgani zations method Organization interface 32 getDescription method Regis tryObject interface 24 getEmailAddresses method User interface 30 getEventType method Audit ableEvent interface 34 getExtension method Telephone Number interface 30 getExternalldentifiers method RegistryObject interface 26 getExternalLinks method Regis tryObject interface 27 getFirstName method PersonName interface 30 getId method Key interface 25 getIdentificationScheme meth od ExternalIdenti fier interface 26 getKey method RegistryObject interface 25 getLastName method PersonName interface 30 getLid method RegistryObjec tImp1 class 25 getMiddleName method Person Name interface 30 getName method RegistryObject interface 24 getNumber method TelephoneNum ber interface 29 getObjectType method Registry Object interface 25 getParentOrganization method Organization interface 32 getPersonName method User inter face 30 getPostalAddress metho
362. o form a hierarchy of organizations The following code fragment creates an organization and specifies its name description postal address and telephone number Create organization name and description Organization org blcm createOrganization The ebXML Coffee Break InternationalString is blcm createInternationalStringC Purveyor of the finest coffees Established 1905 org setDescription is create postal address for 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 Type US PostalAddress postAddr blcm createPostalAddress streetNumber street city state country postalCode type org setPostalAddress postAddr 51 52 DEVELOPING CLIENTS FOR THE SERVICE REGISTRY create telephone number for organization TelephoneNumber tNum blcm createTelephoneNumber tNum setCountryCode 1 tNum setAreaCode 100 tNum setNumber 100 1000 tNum setType OfficePhone Collection tNums new ArrayList tNums add tNum org setTelephoneNumbers tNums The telephone number type is the value of a concept in the PhoneType classifica tion scheme OfficePhone MobilePhone HomePhone FAX or Beeper To create a hierarchy of organizations use the Organization addChildOrga nization method to add one organizat
363. oc gt lt javadoc gt lt package gt CUSTOMIZATION OVERVIEW 63 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 namexXm1Transform 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 e lt nameXmlTransform gt 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 imp1lClass implClass 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
364. ocument In JAXB Documents marshalling involves parsing an XML content object tree and writing out an XML document that is an accurate representation of the original XML document and is valid with respect the source schema JAXB can mar shal XML data to XML documents SAX content handlers and DOM nodes THE JAXB BINDING PROCESS The J AXB Binding Process Figure 1 2 shows what occurs during the JAXB binding process Derived TEVE compile Classes validate follows instances of ra _ mS Document Objects marshal Figure 1 2 Steps in the JAXB Binding Process 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 XML SCHEMA TO JAVA CLASSES WITH JAXB
365. od Extrinsi cObject interface 61 63 setNumber method TelephoneNum ber interface 51 setObjectType method Extrinsi cObjectImp 1 class 61 63 setPersonName method User inter face 53 setPostalAddress method Orga nization interface 51 setSpecificationObject method SpecificationLink interface 63 setTelephoneNumbers method Or ganization interface 51 setTelephoneNumbers method Us er interface 53 setting property values 97 setType method TelephoneNumber interface 51 setUrl method User interface 53 setValidateURI method Exter nalLink interface 50 setValidateURI method Service Binding interface 55 show command 99 Sign element 136 SignatureKeyCallback 178 180 signatures verifying 214 216 Signature VerificationKeyCall back 181 signing SOAP messages 128 Slot interface 13 adding objects 50 retrieving objects 28 slots adding to registry objects 297 SOAP messages encrypting 128 signing 128 verifying 128 specification links adding to service bindings 301 SpecificationLink interface 13 using extrinsic objects 62 SQL statements executing 73 97 sqlselect command line option 73 starting the Admin Tool 70 StatusType classification scheme 19 stopping the Admin Tool 94 SubjectAccessor API INDEX 133 using 196 SubjectGroup scheme 19 SubjectRole classification scheme 19 Sun Java System Service Registry changing the state of objects 65 getting access 7 implementing clients 1 publ
366. of the User message and the SAML Assertion This scenario is not demonstrated in this sample application e Scenario 3 Sender Vouches Signed The request contains a sender vouches SAML assertion The Asser tion and the Body elements are signed A reference to the certificate used to verify the signature is provided in the header The response does not contain a security header In this scenario the basis of trust is the Requester s certificate The Requester s private key is used to sign both the SAML Assertion and the message Body The Responder relies on the Requester who vouches for the contents of the User message and the SAML Assertion e Scenario 4 Holder of Key The request contains a holder of key SAML assertion The assertion is signed by the assertion issuer with an enveloped signature The certificate used to verify the issuer signature is contained within the assertion signa ture The message body is signed by the Requester The certificate used to SAML INTEROP SAMPLE CONFIGURATION FILES 251 verify the Requester s signature is contained in the assertion Subject Confirmation The response does not contain a security header In this scenario the basis of trust is the Assertion Issuer s certificate The Assertion Issuer s private key is used to sign the SAML Assertion for the User The Responder relies on the Assertion Issuer to have issued the assertion to an authorized User SAML Interop Sample Configu
367. ol 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 JWSDP_HOME gt jaxb samples 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 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 79 80 USING JAXB The example xsd Schema The XML schema lt JWSDP_HOME gt jaxb samples 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
368. ome of the javax xml bind interfaces Implementations of JAXB can extend these classes and implement the abstract methods These APIs are not intended to be directly used by applications using JAXB architecture The main package in the JAXB binding framework javax xml bind is described in more detail below More About javax xml bind The three core functions provided by the primary binding framework package javax xm1 bind are marshalling unmarshalling and validation The main cli ent entry point into the binding framework is the JAXBContext class JAXBContext provides an abstraction for managing the XML Java binding infor mation necessary to implement the unmarshal marshal and validate operations A client application obtains new instances of this class by means of the newInstance contextPath method for example JAXBContext jc JAXBContext newInstance com acme foo com acme bar The contextPath parameter contains a list of Java package names that contain schema derived interfaces specifically the interfaces generated by the JAXB binding compiler The value of this parameter initializes the JAXBContext object to enable management of the schema derived interfaces To this end the JAXB BINDING XML SCHEMA TO JAVA CLASSES WITH JAXB provider implementation must supply an implementation class containing a method with the following signature public static JAXBContext createContext String contextPath ClassLoader classLoade
369. ommand 1s htm The Admin Tool echoes your commands and the tool s responses to the screen and then exits after your commands have been executed Make sure that you properly escape any characters that are significant to your shell INTERACTIVE MODE 71 Interactive Mode To run the Admin Tool in interactive mode start the Admin Tool shell by speci fying no options on the command line java jar lt JWSDP_HOME gt registry lib admin tool jar The Admin Tool displays the following prompt and waits for your input admin gt Admin tool Command line Options The Admin Tool recognizes the command line options listed in Synopsis and described in Options Synopsis alias alias command commands debug help keypass keypass localdir localdir locale locale registry url root locator create sqlselect SQL_statement v verbose Options alias The alias to use when accessing the user s certificate in the keystore At this release this option is not meaningful command The Admin Tool command sequence to run instead of getting commands from the interactive shell Use a semicolon to separate multiple com mands It is not necessary to include a quit command in commands If you need to use a semicolon that is not a command separator precede it by a backslash 3 ADMINISTERING THE SERVICE REGISTRY The shell in which you run the Admin Tool may require you to escape the backslash with a
370. omplexType gt lt xs complexType name UsernameToken_T gt lt xs attribute name id type id_T use optional gt lt xs attribute name name type xs string use optional gt lt xs attribute name password type xs string use optional gt lt xs attribute name useNonce type xs boolean use optional default true gt lt xs attribute name digestPassword type xs boolean use optional default true gt lt xs complexType gt lt xs complexType name RequireUsernameToken_T gt lt xs attribute name id type id_T use optional gt lt xs attribute name nonceRequired type xs boolean use optional default true gt lt xs attribute name passwordDigestRequired type xs boolean use optional default true gt lt xs attribute name maxClockSkew type xs decimal use optional default 60 gt lt xs attribute name timestampFreshnessLimit type xs decimal FORMAL SCHEMA DEFINITION 107 use optional default 300 gt lt xs attribute name maxNonceAge type xs decimal use optional default 900 gt lt xs complexType gt lt xs complexType name Encrypt_T gt lt xs sequence minOccurs 0 gt lt xs choice minOccurs 0 maxOccurs 1 gt lt xs element name X509Token type X509Token_T gt lt xs element name SAMLAssertion type SAMLAssertion_T gt lt xs element name SymmetricKey type SymmetricKey_T gt lt xs choice gt lt xs element name KeyEncryptionMethod type
371. on The Classifications table which may be empty appears 2 Click Add A Details Panel window opens 3 Type a name and description for the classification 4 Click the Select ClassificationScheme or Concept button A ClassificationScheme Concept Selector window opens 5 Expand the ClassificationSchemes node then expand concept nodes until you have selected the leaf node you want to use 6 Click OK to close the ClassificationScheme Concept Selector window The classification scheme and concept appear in the Details Panel win dow 7 Click Add to close the Details Panel window The new version of the object appears in the Registry Objects area 8 Click Save in the Details area for the object 295 296 USING THE SERVICE REGISTRY WEB CONSOLE Adding an Extemal Identferto an Object To create an external identifier you use an external classification scheme one whose values are not known to the Registry because the classification scheme has no concepts To add an external identifier to an object search for the appropriate classification scheme then enter a value Follow these steps 1 In the Details area for the object click the Externalldentifiers tab The Externalldentifiers table which may be empty appears Click Add A Details Panel window opens Type a name and description for the external identifier Click the Select ClassificationScheme button A ClassificationScheme Concept Selector wi
372. on 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 Similarly individual nodes within the schema to which customizations are to be applied must be specified using XPath notation for example 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 When its parent is an lt xs appinfo gt element When it is an ancestor of another lt jxb bindings gt element 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 59 60 USING JAXB Scope Inhentance and Precedence Default JAXB bindings can be customized or overridden at four different levels or scopes as described in Table
373. one of these objects is not owned by you The owner of an object can use an access control policy to restrict the right to create an extramural association with that object as a source or target Creating Associations Example For an example of creating an association see lt INSTALL gt registry samples publish association src JAXRPublishAssociation java This example creates a RelatedTo association between any two objects whose unique identifi ers you specify For example you could specify the identifiers of the two child 60 DEVELOPING CLIENTS FOR THE SERVICE REGISTRY organizations created in Creating and Retrieving an Organization Hierarchy Example page 53 To run the example follow these steps 1 Go to the directory lt INSTALL gt registry samples publish associa tion 2 Type the following command ant run Didl string1 Did2 string2 Whether the association is intramural or extramural depends upon who owns the two objects Storing Items in the Repository As About Registries and Repositories page 1 explains the Registry includes a repository in which you can store electronic content For every item you store in the repository you must first create a type of RegistryObject called an ExtrinsicObject When you save the ExtrinsicObject to the Registry the associated repository item is also saved Creating an Extrinsic Object To create an ExtrinsicObject you first need to create a javax activa tion DataHandler o
374. ons primer po Public interface that binds to the schema complexType Items java named Items ABOUT THE SCHEMA TO JAVA BINDINGS 33 Table 2 3 Schema Derived JAXB Classes in the Basic Examples Continued 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 complexType 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 primer po imp1 PurchaseOrderType Imp1 java Implementation of PurchaseOrderType 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
375. ons 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 Binding The JAXB binding compiler is the core of the JAXB processing model Compiler Its function is to transform or bind a source XML schema to a set of JAXB content classes in the Java programming language Basically you run the JAXB binding compiler using an XML schema optionally with custom binding declarations as input and the binding compiler gener ates Java classes that map to constraints in the source XML schema Implementation The JAXB binding framework implementation is a runtime API that pro of vides interfaces for unmarshalling marshalling and validating XML javax xm1 bind content in a Java application The binding framework comprises inter faces in the javax xml1 bind package Schema Derived These are the schema derived classes generated by the binding JAXB Classes compiler The specific classes will vary depending on the input schema BINDING XML SCHEMA TO JAVA CLASSES WITH JAXB Table 1 1 Core Components in a JAXB Implementation Continued Java In the context of JAXB a Java application is a client application that uses Application the JAXB binding framework to unmarshal XML data validate and mod ify Java content objects and marshal Java content back to XML data Typically the JAXB binding framework is wr
376. oors of the library to create a concept for each floor of the library and then adds the concept to the classification scheme for int i 0 i lt floors length i Concept con blcm createConcept cs floors i floors i cs addChi ldConcept con For each concept you can create more new concepts and call Con cept addChi ldConcept to create another level of the hierarchy When you save the classification scheme the entire concept hierarchy is also saved Creating Classification Schemes Example For an example of creating a classification scheme see lt INSTALL gt registry samples classification schemes src JAXRPublishScheme java This example creates a classification scheme named LibraryFloors and a concept CREATING OBJECTS hierarchy that includes each floor of the library and the subject areas that can be found there To run the example follow these steps 1 Go to the directory lt INSTALL gt registry samples classification schemes 2 Type the following command ant pub scheme To display the concept hierarchy use the program lt INSTALL gt registry sam ples classification schemes src JAXRQueryScheme java This example displays the concept hierarchy for any classification scheme you specify To run the example follow these steps 1 Go to the directory lt INSTALL gt registry samples classification schemes 2 Type the following command ant query scheme Dname LibraryFloors To delete this classi
377. or 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 EventParse java Located in the lt JWSDP_HOME gt sjsxp samples event directory Event Parse java demonstrates how to use the StAX cursor API to read an XML doc ument 116 STREAMING API FOR XML 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 Fi leInputStream filename Creating an Event Iterator The third step is to create an event iterator XMLEventReader r factory createXMLEventReader filename new Fi leInputStream fi lename while r hasNextQ XMLEvent e r nextEvent System out printIn e toStringQO Getting the Event Steam The final step is to get the underlying event stream public final static String getEventTypeString Cint 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 c
378. ower 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 sjsxp jar which is located in the lt JWSDP_HOME gt sjsxp lib directory Included with this SJSXP EA distribution are code samples that illustrate how the implementation works These samples are described in the Sample Code sec tion later in this chapter Before proceeding with the sample code there are three important aspects of the SJSXP about which you should be aware e SJSXP JAR Files e Reporting CDATA Events e SJSXP Factories Implementation These three topics are discussed below SJ SXP J AR Files There are two JAR files in the SJSXP implementation Both of these JARs are located in the lt JWSDP_HOME gt sjsxp lib directory e sjsxp jar Sun implementation JAR for SJSXP e jsr173_api jar Standard API JAR for JSR 173 Complete listings of the contents of these two JARs are provided in Appendix B SJSXP JAR Files 108 STREAMING API FOR XML 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 propert
379. owing sections of this addendum Setting System Properties Configuring a JCE Provider Setting Build Properties 2 Start the selected container and make sure the server is running To start the Application Server a From a Unix machine enter the following command from a terminal window asadmin start domain domainl b From a Windows machine choose Start Programs Sun Microsystems J2EE 1 4 Start Default Server 3 Modify the build properties file to set up the security configuration that you want to run for the client and or server See Simple Sample Security Con figuration Files for more information on the security configurations options that are already defined for the sample application 225 226 UNDERSTANDING AND RUNNING THE XWS SECURITY SAMPLE APPLICATIONS 4 Build and run the application from a terminal window or command prompt e On the Application Server the command to build and run the applica tion is asant run sample e On the other containers the command to build and run the application is ant run sample Note To run the sample against a remote server containing the deployed endpoint use the run remote sample target in place of the run sample target In this situa tion make sure that the endpoint host endpoint port http proxyHost http proxyPort and service ur properties are set correctly in the build prop erties file as discussed in Setting Build Properties before running the sample If
380. path config config rpcenc file gt 173 174 INTRODUCTION TO XML AND WEB SERVICES SECURITY lt classpath gt lt pathelement location build home server WEB INF classes gt lt path refid app classpath gt lt classpath gt lt wscompi le gt lt target gt An example of the target that runs the wscompile utility with the security option pointing to the security configuration file specified in the build proper ties file to generate the client side artifacts from the simple sample applica tion looks like this lt target name gen client depends prepare description Runs wscompile to generate client side artifacts gt lt echo message Running wscompile gt lt wscompile fork true verbose jaxrpc tool verbose keep true client true security client security config base build home client features config client config rpcenc file gt lt classpath gt lt fileset dir build home client gt lt include name Secenv handler jar gt lt fileset gt lt path refid app classpath gt lt classpath gt lt wscompi le gt lt target gt Refer to the documentation for the wscompile utility in Useful XWS Security Com mand Line Tools for more information on wscompi 1e options Are There Any Sample Applications Demonstrating XWS Sec unty This release of the Java WSDP includes many example applications that illus trate how a JAX RPC or stand alone SAAJ appli
381. ple java classpath 1 lib sjsxp jar lib jsr173_api jar cursor CursorParse x 1 samples data BookCatalogue xm Again if the jsr173_api jar and sjsxp jar files are in your CLASS PATH you do not need to use the classpath option here Sample XML Document The sample XML document BookCatalogue xm1 used by most of the SJSXP sample classes is located in the lt JWSDP_HOME gt sjsxp samples 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 gt lt BookCatalogue xmlIns 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 111 112 STREAMING API FOR XML 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 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 CursorParse java Located in the lt JWSDP_HOME gt sjsxp samples cursor directory Cursor Parse java demonstrates using the StAX cursor API to rea
382. ple home lt your_name gt jwsdp 1 6 3 Set SJSAS_HOME to the location of your Application Server installation directory for example home lt your_name gt SUNWappserver If you are deploying onto a different container set SJSWS_HOME or TOMCAT_HOME instead 4 Set ANT_HOME to the location where the asant or ant executable can be found If you are running on the Application Server this will be lt SJSAS_HOME gt bin If you are running on a different container this location will probably be lt JWSDP_HOME gt apache ant bin 5 Set the PATH variable so that it contains these directories lt JWSDP_HOME gt jwsdp shared bin lt SJISAS_HOME gt bin lt ANT_HOME gt and lt JAVA_HOME gt bin Configuring a J CE Provider You only need to perform the steps in this section if you are running Java WSDP 1 6 on J2SE 1 4 x The Java Cryptography Extension JCE provider included with J2SE 1 4 x does not support RSA encryption Because the XWS Security sample applications use RSA encryption you must download and install a JCE provider that does support RSA encryption in order for these sample applications to run if you are using encryption and if you are using a version of the Java SDK prior to version 1 5 0 207 208 UNDERSTANDING AND RUNNING THE XWS SECURITY SAMPLE APPLICATIONS Note RSA is public key encryption technology developed by RSA Data Security Inc The acronym stands for Rivest Shamir and Adelman the
383. primer po 2 A JAXBContext instance is created for handling classes generated in primer po JAXBContext jc JAXBContext newInstance primer po 3 An Unmarshaller instance is created and a valid po xm1 document is unmarshalled into a Java content tree Note that po xm1 is valid at this point invalid data will be added later in this example Unmarshaller u jc createUnmarshallerQ PurchaseOrder po PurchaseOrder u unmarshal new FileInputStream po xml 4 A reference is obtained for the first item in the purchase order Items items po getItems List itemTypeList items getItem Items ItemType item Items ItemType itemTypeList get 5 Next the item quantity is set to an invalid number When validation is enabled later in this example this invalid quantity will throw an exception item setQuantity new BigInteger 5 Note If enableFailFastCheck was true and the optional FailFast validation method was supported by an implementation a TypeConstraintException would be thrown here Note that the JAXB implementation does not support the FailFast 54 USING JAXB feature Refer to the JAXB Specification for more information about FailFast val idation 6 A Validator instance is created and the content tree is validated Note that the Validator class is responsible for managing On Demand valida tion whereas the Unmarsha1 ler class is responsible for managing Unmar shal Time validation dur
384. productName gt Lawnmower lt productName gt lt quantity gt 1 lt quantity gt lt USPrice gt 148 95 lt USPrice gt lt comment gt Confirm this is electric lt comment gt lt item gt lt item partNum 926 AA gt lt productName gt Baby Monitor lt productName gt lt quantity gt 1 lt quantity gt lt USPrice gt 39 98 lt USPrice gt lt shipDate gt 1999 05 21 lt shipDate gt lt item gt lt items gt lt purchaseOrder gt The root element purchaseOrder contains the child elements shipTo bi11To comment and items All of these child elements except comment contain other XML SCHEMAS child elements The leaves of the tree are the child elements like name street city and state which do not contain any further child elements Elements that contain other child elements or can accept attributes are referred to as complex types Elements that contain only PCDATA and no child elements are referred to as simple types The complex types and some of the simple types in po xm1 are defined in the purchase order schema below Again this example schema po xsd is derived from the W3C s Schema Part 0 Primer http ww w3 org TR 2001 REC xml schema 0 20010502 lt xsd schema xmIns xsd http www w3 org 2001 XMLSchema gt lt xsd element name purchaseOrder type PurchaseOrderType gt lt xsd element name comment type xsd string gt lt xsd complexType name PurchaseOrderType gt lt xsd sequence gt lt xsd element n
385. ps to be applied to the resource s content before it is digested It looks like this lt xwss SecurityConfiguration dumpMessages true xmIns xwss http java sun com xml ns xwss config gt lt xwss Sign gt lt xwss X509Token certificateAlias xws security client gt lt xwss CanonicalizationMethod algorithm http www w3 org 2001 10 xml exc cl4n gt lt xwss SignatureMethod algorithm http www w3 org 2000 09 xmldsig rsa shal gt lt xwss SignatureTarget type uri value gt lt xwss DigestMethod algorithm http ww w3 org 2000 09 xmldsig shal gt lt xwss Transform algorithm http www w3 org TR 1999 REC xpath 19991116 gt lt xwss AlgorithmParameter name XPATH value SOAP ENV Envelope SOAP ENV Header wsse Security ds Signature 1 ds KeyInfo wsse SecurityTokenReference gt lt xwss Transform gt lt xwss Transform algorithm http THE API SAMPLE SECURITY CONFIGURATION FILES 239 docs oasis open org wss 2004 01 0asis 200401 wss soap message security 1 0 STR Transform gt lt xwss AlgorithmParameter name CanonicalizationMethod value http www w3 org 2001 10 xm1 exc cl4n gt lt xwss Transform gt lt xwss Signaturelarget gt lt xwss Sign gt lt xwss SecurityConfiguration gt The signv3 xm1 file looks the same as signv1 xm1 file except that it sends the subject key identifier extension value of the certificate instead of the actual cer tificate along with t
386. queries on the Registry for objects that are not restricted by an access control policy To perform queries for restricted objects to add data to the Registry or to update Registry data however a user must obtain permission from the Registry to access it The Registry uses client certificate authentication for user access To create a user that can submit data to the Registry use the User Registration Wizard of the Web Console that is part of the Registry software You can also use an existing certificate obtained from a certificate authority You will specify your user name and password for some of the JAXR client example programs along with information about the location of your certificate Establishing a Connection to the Registry 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 Creating a Connection Factory e Creating a Connection DEVELOPING CLIENTS FOR THE SERVICE REGISTRY Creating a Connection Factory A client creates a connection from a connection factory To use JAXR in a stand alone client program you must obtainan instance of the abstract class ConnectionFactory To do so call the getConnectionFactory method in the JAXR provider s JAXRUti lity class import org freebxml omar client xml registry util JAXRUtility ConnectionFactory factory JAXRUtility getConnectionFactoryQ Creating a Connection To create
387. r throws JAXBException Note The JAXB provider implementation must generate a jaxb properties file in each package containing schema derived classes This property file must contain a property named javax xml bind context factory whose value is the name of the class that implements the createContext API The class supplied by the provider does not have to be assignable to javax xm1 bind JAXBContext it simply has to provide a class that implements the createContext API By allowing for multiple Java packages to be specified the JAXBContext instance allows for the management of multiple schemas at one time More About Unmarshalling The Unmarshaller class in the javax xml bind package provides the client application the ability to convert XML data into a tree of Java content objects The unmarshal method for a schema within a namespace allows for any global XML element declared in the schema to be unmarshalled as the root of an instance document The JAXBContext object allows the merging of global ele ments across a set of schemas listed in the contextPath Since each schema in the schema set can belong to distinct namespaces the unification of schemas to an unmarshalling context should be namespace independent This means that a client application is able to unmarshal XML documents that are instances of any of the schemas listed in the contextPath for example JAXBContext jc JAXBContext newInstance com acme foo com acme
388. r a particular receiver When the message is sent from the initial sender it may pass through intermediate nodes before reaching its intended receiver In this scenario the encrypted portions continue to be opaque to any intermediate nodes and can only be decrypted by the intended receiver For this reason message level security is also sometimes referred to as end to end secu rity 127 128 INTRODUCTION TO XML AND WEB SERVICES SECURITY Overview This release includes the following XWS Security features e Support for securing JAX RPC applications at the service port and oper ation levels e XWS Security APIs for securing both JAX RPC applications and stand alone applications that make use of SAAJ APIs only for their SOAP mes saging Note The XWS Security EA 2 0 APIs are intended to insulate XWS Security users from possible changes in the internal APIs however these APIs are subject to minor changes between 2 0 EA and 2 0 FCS 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 claim is the identity of the sender identified by a user name and pass word Support for SAML Tokens and the WSS SAML Token Profile partial
389. r the enumeration class e You can have zero or more lt typesafeEnumMember gt declarations embed ded in a lt typesafeEnumClass gt declaration CUSTOMIZATION OVERVIEW 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 For inline annotations 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 custo
390. rListener class com sun xm1 stream XMLDTDScannerImp1 class com sun xml stream XMLDocumentFragmentScannerImp1 class com sun xml stream XMLDocumentFragmentScannerImp1 Driver class com sun xml stream XMLDocumentFragmentScannerImp1 Element clas Ss com sun xml stream XMLDocumentFragmentScannerImp1 ElementStack class com sun xml stream XMLDocumentFragmentScannerImp1 E1lementStack 2 class com sun xml stream XMLDocumentFragmentScannerImp1 FragmentCont entDriver class com sun xm1 stream XMLDocumentScannerImp1 class com sun xm1 stream XMLDocumentScannerImp1 ContentDriver class com sun xm1 stream XMLDocumentScannerImp1 DTDDriver class com sun xml stream XMLDocumentScannerImp1 PrologDriver class com sun xml stream XMLDocumentScannerImp1 TrailingMiscDriver c lass com sun xml1 stream XMLDocumentScannerImp1 XMLBufferListenerImp 1 class com sun xml1 stream XMLDocumentScannerImp1 XMLDec1Driver class com sun xm1 stream XMLEntityHandler class com sun xml stream XMLEntityManager class com sun xml stream XMLEntityManager RewindableInputStream clas s com sun xml stream XMLEntityReader class com sun xml stream XMLEntityReaderImpl class com sun xml stream XMLEntityStorage class com sun xml stream XMLErrorReporter class com sun xml stream XMLEventReaderImpl class com sun xml stream XMLNSDocumentScannerImpl class com sun xml stream XMLNSDocumentScannerImpl NSContentDriver c l ass SJSXP JAR 117 com sun xm1 stream XMLNamespaceBinder class com sun xm1 stream XML
391. ration Filles The following sections provide the example configuration files for SAML interop scenarios 1 3 and 4 Sender Vouches Sample Configuration Files Holder Of Key Sample Configuration Files Sender Vouc hes Sample Configuration Files The security configuration pair sv saml client3 xml and sv saml server3 xm1 enable the following tasks as required by Scenario 3 e Client contains a sender vouches SAML assertion e Client signs the assertion and the body elements e Client includes a reference to the certificate used to verify the signature in the header e Client sends the request body e Server verifies that a SAML assertion is received e Server verifies the signature e Server sends the response which does not contain a security header The sv saml client3 xm1 file looks like this lt xwss JAXRPCSecurity xmIns xwss http java sun com xml ns xwss config gt lt xwss Service gt lt xwss SecurityConfiguration dumpMessages true gt lt xwss SAMLAssertion type SV strId SV 123 gt lt xwss Sign includeTimestamp false gt lt xwss X509Token certificateAlias xws security client gt lt xwss Target type qname gt http schemas xmlsoap org soap 252 UNDERSTANDING AND RUNNING THE XWS SECURITY SAMPLE APPLICATIONS envelope Body lt xwss Target gt lt xwss SignatureTarget type uri value SV 123 gt lt xwss Transform algorithm http docs oasis open org wss 2004 01 0asis 200401 w
392. ream is used by the con figured log handler Messages are logged at the INFO level The example code is found in the api sample com sun wss sample direc tory The XWSSProc essor Interface The XwSSProcessor interface defines methods for securing an outbound SOAP Message and verifying the security in an inbound SOAPMessage An XWSSPro cessor can add and or verify security in a SOAPMessage in the ways defined by the OASIS WSS 1 0 specification The XwSSProcessor interface contains the following methods e secureOutboundMessage This method adds security to an outbound SOAPMessage according to the security policy inferred from the SecurityConfiguration with which this XWSSProcessor was initialized e verifyInboundMessage This method verifies security in an inbound SOAPMessage according to the security policy inferred from the SecurityConfiguration with which this XwSSProcessor was initialized 233 234 UNDERSTANDING AND RUNNING THE XWS SECURITY SAMPLE APPLICATIONS APIi Sample Client Code The client code samples api sample com sun wss sample Client java uses the XWSSProcessor APIs to secure SOAP messages according to the secu rity policy inferred from the SecurityConfiguration with which this XWSSPro cessor was initialized The following code demonstrates how this is done public static void main String args throws Exception FileInputStream clientConfig FileInputStream serverConfig try read client side secur
393. ream to allocated event objects that can be freely reused and the API itself can be extended to handle custom events 104 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 true 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
394. rectories Security Configuration fles for Enabling Dynamic Policy To specify the request and or response security policy dynamically at runtime you need to enable Dynami cPolicyCal 1back by setting the enableDynami cPol icy flag on the lt xwss SecurityConfiguration gt element The application defined runtime parameters can then be set by the application and passed into the ProcessingContext which is made available to the CallbackHandler as a DynamicApplicationContext The CallbackHandler can then modify an existing policy or set a completely new policy into the Callback As you can see the security configuration files for this example are very simple because the actual security policy that will be applied at runtime is being decided by SecurityEnvironmentHandler The SecurityEnvironmentHandler is dis cussed in Setting Security Policies at Runtime The security configuration file for the client dynamic client xm1 looks like this lt xwss JAXRPCSecurity xmIns xwss http java sun com xml ns xwss config gt lt xwss Service gt lt the exact policy to apply will be decided by the SecurityEnvironmentHandler at runtime gt lt xwss SecurityConfiguration dumpMessages true enable DynamicPol icy true gt lt xwss SecurityConfiguration gt lt xwss Service gt lt xwss SecurityEnvironmentHandler gt SETTING SECURITY POLICIES AT RUNTIME com sun xml wss sample SecurityEnvironmentHandler lt xwss SecurityEnvi
395. 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 validation 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 implem
396. ring alias string keypass string postl type string postl city string postl country string postl postalcode string post1l stateOrProvince string postl street string postl streetNumber string post2 type string post2 city string post2 country string post2 postalcode string post2 stateOrProvince string post2 street string post2 streetNumber string post3 type string post3 city string post3 country string post3 postalcode string post3 stateOrProvince string post3 street string post3 streetNumber string telephonel type string telephonel areaCode string telephonel countryCode string telephonel extension string telephonel number string telephonel URL string telephone2 type string telephone2 areaCode string telephone2 countryCode string telephone2 extension string telephone2 number string telephone2 URL string telephone3 type string telephone3 areaCode string telephone3 countryCode string telephone3 extension ADD USER string telephone3 number string telephone3 URL string emaill type string emaill address string email2 type string email2 address string email3 type string email3 address string Descnption The add user command adds a User object A User object contains at least one PostalAddress TelephoneNumber and EmailAddress object The information that you provide is checked for validity using the same criteria
397. rity configuration pair dump client xml and dump server xml1 have no security operations These options enable the following tasks e Dump the request before it leaves the client e Dump the response upon receipt from the server The container s server logs also contain the dumps of the server request and response See Running the Simple Sample Application for more information on viewing the server logs 213 214 UNDERSTANDING AND RUNNING THE XWS SECURITY SAMPLE APPLICATIONS Encrypting the Request and or the Response The security configuration pair encrypt client xml and encrypt server xm enable the following tasks e Client encrypts the request body and sends it e Server decrypts the request and sends back a response The encrypt client xm file looks like this lt xwss JAXRPCSecurity xmIns xwss http java sun com xml ns xwss config gt lt xwss Service gt lt xwss SecurityConfiguration dumpMessages true gt lt Since no targets have been specified below the contents of the soap body would be encrypted by default gt lt xwss Encrypt gt lt xwss X509Token certificateAlias slas gt lt xwss Encrypt gt lt xwss SecurityConfiguration gt lt xwss Service gt lt xwss SecurityEnvironmentHandler gt sample SecurityEnvironmentHandler lt xwss SecurityEnvi ronmentHand1er gt lt xwss JAXRPCSecurity gt Signing and Verifying the Signature The security configuration pair sign c
398. rivate key required for the signing operation lt xwss Sign gt lt xwss X509Token certificateAlias xws security client gt lt xwss Sign gt The SignatureKeyCal 1back will be initialized by XWS Security run time with an AliasPrivKeyCertRequest in the following manner SignatureKeyCallback sigKeyCallback new SignatureKeyCal 1back new SignatureKeyCallback AliasPrivKeyCertRequest alias The application s SecurityEnvironmentHand1ler implementation then needs to handle the SignatureKeyCallback and use the alias to locate and set the pri vate key and X 509 certificate pair on the AliasPrivKeyCertRequest The fol lowing code shows how this callback is handled in the handle method of SecurityEnvironmentHandler shipped with the simple sample else if Ccallbacks i instanceof SignatureKeyCallback SignatureKeyCallback cb SignatureKeyCallback callbacks i WRITING SECURITYENVIRONMENTHANDLERS if C cb getRequest instanceof SignatureKeyCallback AliasPrivKeyCertRequest SignatureKeyCallback AliasPrivKeyCertRequest request SignatureKeyCallback AliasPrivKeyCertRequest cb getRequest String alias request getAliasQ if keyStore null initKeyStoreQ try X509Certificate cert X509Certificate keyStore getCertificate alias request setx509Certificate cert Assuming key passwords same as the keystore password PrivateKey privKey PrivateKey keyStore getKey alias keyStorePassword toCharArray
399. rm 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 xjc strictly enforces the rules outlined in the Compati bility chapter of the JAXB Specification Specifically Appendix E 2 defines a set of W3C XML Schema features that are not completely supported by JAXB v1 0 In some cases you may be able to use these extensions with the extension switch In the default strict mode you are also limited to using only the binding customizations defined in the specification By using the extension switch you can enable the JAXB Vendor Extensions extension JAXB COMPILER OPTIONS 31 Table 2 2 xjc Command Line Options Continued Option or Argument b lt file gt Description Specify one or more external binding files to process each binding file must have it s own b switch The syntax of the external bind ing 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 for example xjc schemal xsd schema2 xsd schema3 xsd b bindings123 xjb xjc schemal xsd schema2 xsd schema3 xsd b bindings1 xjb b bindings2 xjb b bindings3 xjb Note that the ordering of schema files and bi
400. rmines whether caching is enabled Default is false optional This flag is unused in the current release and has been introduced for future enhancements Table 4 5 Sub elements of Service element SecurityConfiguration Indicates that what follows is the security configuration for the service Port A port within a JAX RPC service Any including zero num ber of these elements may be specified SecurityEnvironmentHandler Specifies the implementation class name of the security envi ronment handler If specified overrides the SecurityEnvi ronmentHand ler specified at the parent level Optional SEMANTICS OF SECURITY CONFIGURATION FILE ELEMENTS 147 Port The lt Port gt element represents a port within a JAX RPC service Table 4 6 pro vides a description of its attributes Table 4 7 provides a description of its sub ele ments Table 4 6 Attributes of Port element Name of the port as specified in the wsdl Required Type of conformance In this release the choice for this attribute is restricted to bsp In this release XWS Security is conformant to Basic Security Profile BSP for messages that are created and sent When conformance is set to bsp mes conformance sages are checked for BSP compliance before being sent For more information on BSP read What is Basic Security Profile BSP This EA implementation of this feature will be more complete in the FCS release optional Table 4
401. ronmentHand1er gt lt xwss JAXRPCSecurity gt The security configuration file for the server dynamic server xml1 looks like this lt xwss JAXRPCSecurity xmIns xwss http java sun com xml ns xwss config gt lt xwss Service gt lt the exact policy to apply will be decided by the SecurityEnvironmentHandler at runtime gt lt xwss SecurityConfiguration dumpMessages true enable DynamicPol icy true gt lt xwss SecurityConfiguration gt lt xwss Service gt lt xwss SecurityEnvironmentHandler gt com sun xml wss sample SecurityEnvironmentHandler lt xwss SecurityEnvi ronmentHand1er gt lt xwss JAXRPCSecurity gt Setting Secunty Policies at Runtime The dynamic policy sample application demonstrates how the request and response security policies can be set at runtime from the Securi tyEnvi ronmen tHandler callback In this sample the SecurityEnvironmentHandler inserts a SignaturePolicy at runtime The SignaturePolicy asks for a signature over the body of the mes sage For the requesting side this is equivalent to using an lt xwss Sign gt element in the configuration file For the receiving side this is equivalent to using an lt xwss RequireSignature gt element in the configuration file Both the request and response contain a signature over the body Note The APIs used in this sample by the SecurityEnvi ronmentHand1ler callback are evolving and hence are subject to modification prior to the re
402. ropriate property name tom SIMPLE SECURITY CONFIGURATIONS SAMPLE APPLICATION cat home or sjsws home and uncomment that entry instead Only one of the container home properties should be uncommented at any one time e username password Enter the appropriate username and password values for a user assigned to the role of admin for the container instance being used for this sample A user with this role is authorized to deploy applications onto the Application Server e endpoint host endpoint port If you changed the default host and or port during installation of the Application Server or other container change these properties to the correct values for your host and port If you installed the Application Server using the default values these properties will already be set to the correct values e VS DIR If you are running under the Sun Java System Web Server enter the directory for the virtual server If you are running under any other container you do not need to modify this property e jwsdp home Set this property to the directory where Java WSDP is installed The keystore and truststore URL s for the client are configured relative to this property e http proxyHost http proxyPort If you are using remote endpoints set these properties to the correct proxy server address and port If you are not using remote endpoints put a comment character before these properties A proxy server will follow the format of myser
403. rs in the Registry Objects area 7 Click Save in the Details area for the object Adding Custom Information to an Object Using Slots A slot contains extra information that would otherwise not be stored in the Reg istry Slots provide a way to add arbitrary attributes to objects To add a slot to an object follow these steps 1 In the Details area for the object click the Slots tab The Slots table which may be empty appears 2 Click Add A Details Panel window opens 3 Type a name for the Slot 4 Optionally type a value in the Slot Type field You may use this field to specify a data type for the slot or to provide a way to group slots together 5 Type a value in the Values field 6 Click Add to close the Details Panel window The new version of the object appears in the Registry Objects area 7 Click Save in the Details area for the object 298 USING THE SERVICE REGISTRY WEB CONSOLE Adding a Postal Address to an Organization or User An Organization or User can have one or more postal addresses To add a postal address to either an Organization or a User follow these steps 1 In the Details area for the Organization or User click the PostalAddresses tab The PostalAddresses table which may be empty appears 2 Click Add A Details Panel window opens 3 Type values in the fields All fields except Street are optional Street Number Street required City State or Province Country
404. rty 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 lt city gt Cambridge lt city gt lt state gt MA lt state gt lt zZip 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 lt city gt Beverly Hills lt city gt lt state gt CA lt state gt lt Zip gt 90210 lt zip gt lt bil1To gt lt items gt lt item partNum 242 NO gt CREATE MARSHAL EXAMPLE 47 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 Create Marshal Example The Create
405. rules are robust enough that a usable binding can be produced with no custom bind ing declaration at all Code examples showing how to customize JAXB bindings are provided in Chap ter 2 21 22 BINDING XML SCHEMA TO JAVA CLASSES WITH JAXB Scope When a customization value is defined in a binding declaration it is associated with a scope A scope of a customization value is the set of schema elements to which it applies If a customization value applies to a schema element then the schema element is said to be covered by the scope of the customization value Table 1 4 lists the four scopes for custom bindings Table 1 4 Custom Binding Scopes Global A customization value defined in lt globalBindings gt has global scope A global scope covers all the schema elements in the source schema and recur sively any schemas that are included or imported by the source schema Schema A customization value defined in lt schemaBindings gt has schema scope A schema scope covers all the schema elements in the target name space of a schema Definition A customization value in binding declarations of a type definition and global declaration has definition scope A definition scope covers all schema elements that reference the type definition or the global declaration Component A customization value in a binding declaration has component scope if the customization value applies only to the schema element that was annotated
406. s com sun xm1 stream events ZephyrEventFactory class com sun xm1 stream util ReadOnlyIterator class com sun xml1 stream writers WriterUtility class com sun xm1 stream writers XMLEventWriterImp1 class com sun xml1 stream writers XMLStreamWriterImp class com sun xm1 stream writers XMLStreamwriterImpl Attribute class com sun xml1 stream writers XMLStreamWriterImp1 ElementStack cl ass com sun xml1 stream writers XMLStreamWriterImp1 ElementState cl ass com sun xml1 stream writers XMLStreamWriterImp1 NamespaceContex tImp1 class com sun xm1 stream xerces imp1 io0 ASCIIReader class com sun xml1 stream xerces imp1 io UCSReader class com sun xm1 stream xerces imp1 io UTF8Reader class com sun xml stream xerces imp1 msg XMLMessageFormatter class 118 SJSXP JAR FILES com sun xml stream xerces uti1 AugmentationsImp1 class com sun xml stream xerces uti 1 AugmentationsImp1 Augmentations ItemsContainer class com sun xml stream xerces uti 1 AugmentationsImp1 LargeContaine r class com sun xml stream xerces uti 1 AugmentationsImp1 Smal1Containe r class com sun xml stream xerces uti 1 AugmentationsImp1 Smal1Containe r Smal1ContainerKeyEnumeration class com sun xml1 stream xerces uti 1 DefaultErrorHandler class com sun xml stream xerces uti1l EncodingMap class com sun xml stream xerces util IntStack class com sun xml stream xerces uti1 MessageFormatter class com sun xm1 stream xerces uti1 NamespaceContextWrapper class com sun xm1 stream xerces uti1 Namesp
407. s 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 55 56 USING JAXB 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 Java 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 a
408. s the database provided with the Registry contains only one The declarative query is the same query performed in Using Declarative Queries Example page 36 The stored query is the GetCallersUser query as in the previous example To run the example follow these steps 1 Go to the directory lt INSTALL gt registry samples query federation 2 Type the following command ant run Publishing Objects to the Registry If a client has authorization to do so it can submit objects to the Service Regis try modify them and remove them A client uses the BusinessLifeCycleMan ager interface to perform these tasks Registries usually allow a client to modify or remove objects only if the objects are being modified or removed by the same user who first submitted them Access policies can control who is authorized to publish objects and perform actions on them Publishing registry objects involves the following tasks e Creating Objects e Saving Objects in the Registry It is important to remember that submitting objects is a multi step task you cre ate the objects and populate them by setting their attributes then you save them The objects appear in the registry only after you save them You may remember that when you search for objects by classification external identifier and the like you create the classification or other object that you are using in the search For an example see Finding Objects by Classification page
409. s the unique identifiers for the saved objects The following code fragment saves an organization and retrieves its key Add organization and submit to registry Retrieve key if successful Collection orgs new ArrayListQ orgs add org BulkResponse response blcm saveOrganizations orgs Collection exceptions response getExceptions if exceptions null System out printInC Organization saved Collection keys response getCollection Iterator keyIter keys iterator if keyIter hasNextQ javax xml registry infomodel Key orgKey javax xml registry infomodel Key keyIter nextQ String id orgKey getIdQ System out printInC Organization key is id If one of the objects exists but some of the data have changed the save methods update and replace the data This normally results in the creation of a new ver sion of the object see Changing the State of Objects in the Registry page 65 MANAGING OBJECTS IN THE REGISTRY 57 Managing Objects in the Registry Once you have published objects to the Registry you can perform opera tions on them This chapter describes these operations Creating Relation ships Between Objects Associations Storing Items in the Repository Organizing Objects Within Registry Packages Changing the State of Objects in the Registry Removing Objects From the Registry and Repository Creating Relationships Between Objects Associations You can create an
410. s appear ing in a server configuration file similarly indicate that the server expects the request to be signed and encrypted respectively The normal behavior of a client or server when it specifies a requirement of the form xwss RequireSignature or xwss RequireEncryption is to throw an exception if the requirement is not met by the received response or request The xwss SecurityEnvironmentHandler element appearing under xwss SecurityConfiguration is a compulsory child element that needs to be specified The value of this element is the name of a Java class that implements the javax security auth callback CallbackHandler interface and handles a set of Callbacks defined by XWS Security There are a set of callbacks that are mandatory and that every CallbackHand1er needs to implement A few call backs are optional and can be used to supply some finer grained information to the XWS Security run time The SecurityEnvironmentHandler and the Cal1 backs are described in Writing SecurityEnvironmentHandlers The SecurityEnvi ron mentHandler is essentially a CallbackHandler which is used by the XWS Security run time to obtain the private keys certificates symmetric keys etc to be used in the signing and encryption operations from the application For more information refer to the API documentation for the com sun xml wss impl callback package which is located in the lt JWSDP_HOME gt xws security docs api directory to find the list of mandatory and
411. s 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 features 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 3 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 3 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
412. s using security configuration files In this tutorial build package and deploy targets are defined and run using the asant tool The asant tool is version of the Apache Ant Java based build tool used specifically with the Sun Java System Application Server Application Server If you are deploying to a different container you can use the Apache Ant tool instead To configure a security configuration file follow these steps 1 Create a security configuration file Creating security configuration files is discussed in more detail in Understanding Security Configuration Files Sample security configuration files are located in the directory lt JWSDP_HOME gt xws security samples simple config 2 Create an asant or ant target in the build xm1 file for your application that passes in and uses the security configuration file s This step is dis cussed in more detail in How Do I Specify the Security Configuration for the Build Files 3 Create a property in the build properties file to specify a security con figuration file to be used on the client side and a security configuration file to be used on the server side This step is discussed in more detail in How Do I Specify the Security Configuration for the Build Files Understanding Secunty Configuration Files Security configuration files are written in XML The elements within the XML file that specify the security mechanism s to use for an application are enclosed within lt xwss
413. scompile utility to generate stubs ties serializers and WSDL files XWS Security has been integrated into JAX RPC through the use of secu rity configuration files The code for performing the security operations on the client and server is generated by supplying the configuration files to the JAX RPC wscompi le tool The wscompi le tool can be instructed to generate security code by making use of the security option and supplying the security configu ration file Note For the 2 0 release of JAX RPC JAX RPC will be renamed to JAX WS JAX WS will become part of the XWS Security 2 0 FCS later this year When this renaming occurs the wscompile tool will be replaced and these steps and the build xml files for the sample applications will need to be modified accordingly An example of the target that runs the wscompile utility with the security option pointing to the security configuration file specified in the build proper ties file to generate server artifacts from the simple sample application looks like this lt target name gen server depends prepare description Runs wscompile to generate server artifacts gt lt echo message Running wscompile gt lt wscompile verbose jaxrpc tool verbose xPrintStackTrace true keep true fork true security server security config import true model bui ld home server WEB INF model rpcenc file base build home server WEB INF classes classpath app class
414. se This Tutorial xii About the Examples xiii Required Software xiv Building the Examples xiv Further Information Xv How to Print This Tutorial Xv Typographical Conventions xvi Feedback xvi Binding XML Schema to J ava Classes with J AXB 1 JAXB Architecture 2 Architectural Overview 2 The JAXB Binding Process 5 JAXB Binding Framework 6 More About javax xml bind 7 More About Unmarshalling 8 More About Marshalling 9 More About Validation 11 XML Schemas 13 Representing XML Content 17 Binding XML Names to Java Identifiers 17 Java Representation of XML Schema 17 Binding XML Schemas 18 Simple Type Definitions 18 Default Data Type Bindings 19 Default Binding Rules Summary 20 iii CONTENTS Customizing JAXB Bindings 21 Scope 22 Scope Inheritance 22 What is Not Supported 23 JAXB APIs and Tools 23 Chapter2 Using JAXB 0c cece cece eee 2D General Usage Instructions 26 Description 26 Using the Examples 28 Configuring and Running the Samples 28 JAXB Compiler Options 30 About the Schema to Java Bindings 32 Schema Derived JAXB Classes 35 Basic Examples 43 Unmarshal Read Example 43 Modify Marshal Example 45 Create Marshal Example 47 Unmarshal Validate Example 51 Validate On Demand Example 52 Customizing JAXB Bindings 54 Why Customize 55 Customization Overview 56 Customize Inline Example 69 Datatype Converter Example 74 External Customize Example 75 Fix Collides Example 79 Bind Choice Example 83 Chapter3 Stre
415. se 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 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 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 CUSTOMIZE INLINE EXAMPLE 71 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 PurchaseOr
416. second backslash G If any command contains spaces enclose the entire command sequence in single or double quotes so that the tool will treat the sequence as one com mand line parameter instead of several If your shell also interprets a semicolon as separating shell commands you always have to put sequences of multiple Admin Tool commands in quotation marks create If necessary create the RegistryPackage specified by the root option as well as any parent RegistryPackage objects as needed This option is valid only if the user running the Admin Tool is authorized to create objects debug Outputs extra information that is useful when debugging help Provides a list of these options keypass The password to use when accessing a user s certificate in the keystore At this release this option is not meaningful localdir The base directory in the local file system for commands that relate to files in the local file system locale The locale for example en or fr_CA to use for selecting the resource bundle to use for error and status messages The default is determined by the Java Virtual Machine registry USING THE ADMIN TOOL The URL of the ebXML registry to which to connect The default is http localhost 8080 soar registry soap root The locator for example registry userData of the RegistryPack age to use as the base for those commands that treat the repository as a tree of RegistryPac
417. ses this code See for example JAXRQueryByName java in Finding Objects by Name Example page 16 Retrieving the Attributes of an Organization or User Every Organization object can have one postal address and multiple telephone numbers in addition to the attributes available to all other objects Every organi zation also has a User object as a primary contact and it may have additional affiliated User objects The attributes for a User object include a PersonName object which has a differ ent format from the name of an object A user can have multiple postal addresses as well as multiple telephone numbers A user can also have multiple email addresses RETRIEVING INFORMATION ABOUT AN OBJECT 29 To retrieve the postal address for an organization call the Organization get PostalAddress method as follows org is the organization PostalAddress pAd org getPostalAddress Once you have the address you can retrieve the address attributes as follows System out printIn Postal Address n pAd getStreetNumber pAd getStreetQ n LLI J pAd k getCi tyO mW y mW pAd getState0rProvince pAd getPostalCode n pAd getCountry Cc pAd getTypeQ To retrieve the primary contact for an organization call the Organiza tion getPrimaryContact method as follows org is the organization User pc org getPrimaryContactQ To retrieve the postal addresses for a user call the User getPostalA
418. so have classifications associated with it In addition to the attributes common to all objects 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 speci fication link which provides the linkage between a service binding and a techni CREATING OBJECTS cal specification that describes how to use the service 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 attribute to false Create services and service Collection services new ArrayListQ Service service blcm createService My Service Name InternationalString is blcm createInternationalStringC My Service Description service setDescription is Create service bindings Collection serviceBindings new ArrayListQ ServiceBinding binding blcm createServiceBindingQ is blcm createInternationalString My Service Binding Name binding setName is is blcm createInternationalString My Service Binding Description binding setDescription is allow us to publish a fictitious URI withou
419. specifies the xwss SymmetricKey child of xwss Encrypt and speci fies the keyAlias attribute on it 5 When the EncryptedKey contains a ds KeyInfo with a key value child Accordingly there are five Request classes with which a DecryptionKeyCal1 back can be initialized Request Inner Classes Defined 4 AliasSymmet ricKeyRequest A Callback initialized with this request should be handled if the symmetric key to be used for decryp tion is mapped to some alias 5 PublicKey BasedPrivateKey Request Request for a private key given the public key Methods in the Request Classes The following methods are present in the AliasSymmet ricKeyRequest class of this Callback public void setSymmet ricKey javax crypto SecretKe y symmetricKey public javax crypto SecretKey getSymmetricKey WRITING SECURITYENVIRONMENTHANDLERS 185 Table 4 41 Summary of Callback classes and their Request types Continued Callback Password Valida tion Callback Description Username Password valida tion A validator that imple ments the PasswordValidator inter face should be set on the call back by the callback handler There are currently two situa tions in which XWS Security will require this Ca11back to perform username password validation 1 When the receiver gets a UsernameToken with plain text user name and password 2 When the receiver gets a UsernameToken with a digested password as sp
420. ss com sun xm1 stream xerces uti 1 XMLResourceldentifierImp1 class com sun xml stream xerces uti1 XMLStringBuffer class com sun xm1 stream xerces uti1 XMLSymbols class JSR173_API JAR 119 com sun xml stream xerces xni Augmentations class com sun xm1 stream xerces xni NamespaceContext class com sun xml stream xerces xni QName class com sun xm1 stream xerces xni XMLAttributes class com sun xml stream xerces xni XMLDTDContentModelHandler class com sun xm1 stream xerces xni XMLDTDHandler class com sun xm1 stream xerces xni XMLDocumentFragmentHandler class com sun xm1 stream xerces xni XMLDocumentHandler class com sun xm1 stream xerces xni XMLLocator class com sun xm1 stream xerces xni XMLResourceldentifier class com sun xml stream xerces xni XMLString class com sun xm1 stream xerces xni XNIException class com sun xml1 stream xerces xni parser XMLComponent class com sun xml1 stream xerces xni parser XMLComponentManager class com sun xml stream xerces xni parser XMLConfigurationException class com sun xml stream xerces xni parser XMLDTDContentModelFilter class com sun xml1 stream xerces xni parser XMLDTDContentModel Source class com sun xml1 stream xerces xni parser XMLDTDFilter class com sun xml1 stream xerces xni parser XMLDTDScanner class com sun xm1 stream xerces xni parser XMLDTDSource class com sun xml stream xerces xni parser XMLDocumentFi lter class com sun xm1 stream xerces xni parser XMLDocumentScanner class com sun xml stream xerces x
421. ss config gt lt xwss Sign gt lt xwss X509Token certificateAlias xws security client gt lt xwss Sign gt lt xwss Sign gt lt xwss X509Token certificateAlias xws security client gt lt xwss Target type qname gt http schemas xmlsoap org soap enve lope Body lt xwss Target gt lt xwss Signaturelarget type xpath value SOAP ENV Envelope SOAP ENV Header wsse Security ds Signature 1 ds KeyInfo wsse SecurityTokenReference gt lt xwss DigestMethod algorithm http ww w3 org 2000 09 xmldsig shal gt lt xwss Transform algorithm http docs oasis open org wss 2004 01 oasis 200401 wss soap message secu rity 1 0 STR Transform gt lt xwss AlgorithmParameter name CanonicalizationMethod value http www w3 org 2001 10 xm1 exc cl14n gt lt xwss Transform gt lt xwss Signaturelarget gt lt xwss Sign gt lt xwss SecurityConfiguration gt Sending a Usemame Token with the SOAP Message The security configuration username xm1 enables the following tasks e Client adds a username password token to an outbound SOAPMessage and sends a request e Client verifies that the inbound SOAPMessage contains a UsernameToken BUILDING AND RUNNING THE API SAMPLE APPLICATION 241 The username xm file looks like this lt xwss SecurityConfiguration dumpMessages true xmIns xwss http java sun com xml ns xwss config gt lt xwss UsernameToken name Ron password noR gt lt xwss
422. ss soap message security 1 0 STR Transform gt lt xwss AlgorithmParameter name CanonicalizationMethod value http www w3 org 2001 10 xml exc c14n gt lt xwss Transform gt lt xwss SignatureTarget gt lt xwss Sign gt lt xwss Timestamp gt lt xwss SecurityConfiguration gt lt xwss Service gt lt xwss SecurityEnvironmentHandler gt sample SecurityEnvironmentHandler lt xwss SecurityEnvi ronmentHand1er gt lt xwss JAXRPCSecurity gt The sv saml server3 xm1 file looks like this lt xwss JAXRPCSecurity xmins xwss http java sun com xml ns xwss config gt lt xwss Service gt lt xwss SecurityConfiguration dumpMessages true gt lt xwss Requirelimestamp gt lt xwss RequireSAMLAssertion type SV gt lt xwss RequireSignature requireTimestamp false gt lt xwss X509Token gt lt xwss Target type qname gt http schemas xmlsoap org soap enve lope Body lt xwss Target gt lt xwss SignatureTarget type uri value SV 123 gt lt xwss RequireSignature gt lt xwss SecurityConfiguration gt lt xwss Service gt lt xwss SecurityEnvironmentHandler gt sample SecurityEnvironmentHandler lt xwss SecurityEnvi ronmentHand1er gt lt xwss JAXRPCSecurity gt The other security configuration files in the samlinterop config directory that contain a sender vouches type of assertion are those in support of Scenario 1 the sv saml client xml and sv saml server xml pair
423. sses generated by the JAXB binding compiler for the basic examples is listed below followed by brief explanations of its func tions The classes listed here are e Comment java e Items java e ObjectFactory java e PurchaseOrder java e PurchaseOrderType java e USAddress java 36 USING JAXB Commentjava In Comment java e The Comment java class is part of the primer po package e Comment is a public interface that extends javax xml bind Element e Content in instantiations of this class bind to the XML schema element named comment e The getValue and setValue methods are used to get and set strings repre senting XML 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 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 getPartNumQ e setPartNum String value e getCommentQ e setComment java lang String value e getUSPriceQ e setUSPrice java math BigDecimal value e getProductName e setProductName String value e getShipDate SCHEMA DERIVED JAXB
424. st argument could be either Organization or organization and the name pattern matches names regardless of case The following code fragment performs a case sensitive search for all registry objects whose names contain the string qString and sorts them in alphabetical order Collection findQualifiers new ArrayListQ findQualifiers add FindQualifier CASE_SENSITIVE_MATCH findQualifiers add FindQualifier SORT_BY_NAME_ASC Collection namePatterns new ArrayListQ namePatterns add qString Find objects with name that contains qString BulkResponse response bqm findObjects RegistryObject findQualifiers namePatterns null null null null Collection orgs response getCollection The percent sign matches any number of characters in the name To match a sin gle character use the underscore _ For example to match both Arg1 and Org2 you would specify a name pattern of _rg_ 15 16 DEVELOPING CLIENTS FOR THE SERVICE REGISTRY Finding Objects by Name Example For an example of finding objects by name see the example lt INSTALL gt regis try samples query name src JAXRQueryByName java To run the example follow these steps 1 Go to the directory lt INSTALL gt registry samples query name 2 Type the following command specifying a string value ant run Dname string The program performs a case insensitive search returning all objects whose names contain the specified string
425. st organizations offer services JAXR has methods that retrieve the services and service bindings for an organization A Service object has all the attributes of other registry objects In addition it normally has service bindings which provide information about how to access the service A ServiceBinding object along with its other attributes normally has 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 through the service binding In addition to these attributes you can use the Service getProvidingOrgani zation method to retrieve the organization that provides a service and you can use the ServiceBinding getService method to retrieve the service for a ser vice binding The following code fragment retrieves the services for the organi zation org Then it retrieves the service bindings for each service and for each service binding its access URI and specification links A specification link in turn has a specification object typically an ExtrinsicObject usage descrip tion an InternationalString object and a Collection of usage parameters that are String values Collection services org getServices Iterator svcIter services iterator while svcIter hasNextQ Service svc Service svcIter nextQ System out printInC Service name getName svc System out printInC Service description getDescr
426. stack trace of the immedi ately preceding command Identifying Registry Objects The primary way to identify registry objects is by name This extends to identi fying RegistryPackage objects by the path from the registry root to the Regis tryPackage For example registry userData is the path to the userData RegistryPackage Some matches for names support wildcards Use a question mark to match a single character and use an asterisk to match zero or more characters Some commands for example cd and chown support identifying objects by their Uniform Resource Name URN which must include a leading urn For example urn uuid 2702f889 3ced 4d49 82d1 e4cd846cb9e4 The chown command also supports using number to refer to a User listed by a previous users command For some commands you can enter names that contain spaces by enclosing the entire name in double quotes or by preceding each space in the name by a back slash THE EFFECT OF LOCALE ON SPECIFYING NAMES The Effect of Locale on Specifying Names A RegistryObject or a RegistryPackage may have multiple names each of which is associated with a different locale The paths and object names that you specify are evaluated with respect to the current locale only When you attempt to select by name a registry object that has multiple names the Registry attempts to match the name that you provide against only one alternative for the registry object s name the choi
427. sted in Table 7 1 Table 7 1 Languages Supported by the Web Console Simplified Chinese China Traditional Chinese Taiwan English United States German Japanese Korean Spanish French Canada Finnish To change the language from the default follow these steps 1 Add the language to your web browser language preferences by following the instructions for the web browser For most browsers you can find the language settings in the General area of the Internet Options Options or Preferences dialog box 2 Make the language your preferred language by placing it first in the list of languages 3 Click the Reset Locale button The labels appear in the appropriate language 286 USING THE SERVICE REGISTRY WEB CONSOLE Changing the Default Language for Registry Content You can publish content to the registry in any of the languages shown in the Con tent Language drop down list in the top banner area if the language is supported on your system The default is the language setting for your web browser To change the language from the default choose the language from the Content Language drop down list Searching the Registry The Search and Explore links in the menu area allow you to search the Registry e Using the Search Menu e Selecting a Query e Searching by Object Type e Searching by Name and Description e Searching by Classification e Viewing Search Results e Usin
428. strates how to enable validation during unmarshalling Example Validate On Demand Demonstrates how to validate a Java content tree at runtime Example Customize Inline Exam Demonstrates how to customize the default JAXB bindings by ple means of inline annotations in an XML schema DESCRIPTION Table 2 1 Sample JAXB Application Descriptions Example Name Datatype Converter Example Similar to the Customize Inline example this example illustrates alternate more terse bindings of XML simpleType definitions to Java datatypes External Customize 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 Fix Collides Example Illustrates how to use customizations to resolve name conflicts reported by the JAXB binding compiler It is recommended that you first run ant fail in the application directory to see the errors reported by the JAXB binding compiler and then look at binding xjb to see how the errors were resolved Running ant alone uses the binding customizations to resolve the name con flicts while compiling the schema Bind Choice Example Illustrates how to bind a choice model group to a Java interface Note These examples are all located in the JWSDP_HOME jaxb samp1les direc tory Each example directory contains several base files e po xsd is the XML schema you will use as input to t
429. stry while process ing protocol messages EventType Occasionally Defines the types of events that can occur in a registry InvocationModel Rarely Defines the different ways that a content management service may be invoked by the Registry 290 USING THE SERVICE REGISTRY WEB CONSOLE Table 7 3 Classification Scheme Usage Continued Classification Scheme Name Description or Purpose Defines the different ways in which a ClassificationScheme may assign the value of the code attribute for its Classi ficationNodes NodeType Occasionally Defines the different ways in which a client NotificationOptionType Rarely may wish to be notified by the registry of an event within a Subscription Defines the different types of RegistryOb ObjectType Occasionally jects a registry may support PhoneType Rarely Defines the types of telephone numbers Defines the query languages supported by QueryLanguage Rarely the Registry Defines the different types of status for a ResponseStatusType Rarely RegistryResponse Defines the different types of status for a StatusType Occasionally RegistryResponse Defines the groups that a user can belong to SubjectGroup Rarely for access control purposes Defines the roles that can be assigned to a Subjectkole Rarely user for access control purposes In the menu area the root of the ClassificationScheme tree is below the Descrip tion fi
430. sun xml 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 JWSDP 1 6 bundle All sample directories used in this section are located off the lt JWSDP_HOME gt sjsxp samples directory The sample XML file used here is located in the data directory off of samples There are seven sample directories distributed with JWSDP 1 6 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 data contains BookCatalogue xml which is the XML document used by the sample classes event contains EventParse java which illustrates how to use the XMLEv entReader event iterator API to read an XML file filter contains MyStreamFilter java which illustrates how to use the Stax Stream Filter APIs In this example the filter accepts only StartEle ment and EndElement events and filters out the remainder of the events readnwrite contains EventProducerConsumer java which illustrates how the StAX producer consumer mechanism can be used to simulta neously read and write XML streams writer contains CursorWriter java which illustrates how to use XML StreamWriter to write an XML fi
431. t 218 UNDERSTANDING AND RUNNING THE XWS SECURITY SAMPLE APPLICATIONS Adding a Timestamp to a Signature The security configuration pair timestamp sign client xml and timestamp sign server xml enable the following tasks e Client signs the request including a timestamp in the request The timestamp sign client xm file looks like this lt xwss JAXRPCSecurity xmIns xwss http java sun com xml ns xwss config gt lt xwss Service gt lt xwss SecurityConfiguration dumpMessages true gt lt Export a Timestamp with the specified timeout interval Cin sec gt lt xwss Timestamp timeout 120 gt lt The above Timestamp would be signed by the following Sign operation by default gt lt xwss Sign gt lt xwss Target type qname gt http xmlsoap org Ping ticket lt xwss Target gt lt xwss Sign gt lt xwss SecurityConfiguration gt lt xwss Service gt lt xwss SecurityEnvironmentHandler gt sample SecurityEnvironmentHandler lt xwss SecurityEnvi ronmentHand1er gt lt xwss JAXRPCSecurity gt Symmetric Key Encryption The security configuration pair encrypt using symmkey client xm l and encrypt server xm1 enable the following tasks e Client encrypts the request using the specified symmetric key This is a case where the client and server security configuration files do not match This combination works because the server requirement is the same the body contents must be encrypt
432. t lt xs choice gt lt xs sequence gt lt xs attribute name id type id_T use optional gt lt xs complexType gt lt xs complexType name OptionalTargets_T gt lt xs choice minOccurs 0 maxOccurs unbounded gt lt xs element name Target type Target_T gt lt xs choice gt lt xs complexType gt lt xs complexType name X509Token_T gt lt xs attribute name id type id_T use optional gt lt xs attribute name strId type id_T use optional gt lt xs attribute name certificateAlias type xs string use optional gt lt xs attribute name keyReferenceType use optional default Direct gt lt xs simpleType gt lt xs restriction base xs string gt lt xs enumeration value Direct gt lt xs enumeration value Identifier gt lt xs enumeration value IssuerSerialNumber gt lt xs restriction gt lt xs simpleType gt lt xs attribute gt lt xs attribute name encodingType use optional gt lt xs simpleType gt lt xs restriction base xs string gt lt xs enumeration value http docs oasis open org wss 2004 0 1 oasis 200401 wss soap message security 1 0 Base64Binary gt lt xs restriction gt lt xs simpleType gt lt xs attribute gt lt xs attribute name valueType type xs string use optional gt lt xs complexType gt lt xs complexType name SAMLAssertion_T gt lt xs attribute name id type id_T use optional gt lt xs attribute name authorityId typ
433. t 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 Signature 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
434. t The prefix list is computed by the implementation and does not need to be specified in the configuration file This transform will be added as the last transform regardless of its placement in the configuration file algorithm SEMANTICS OF SECURITY CONFIGURATION FILE ELEMENTS SignatureMethod The lt SignatureMethod gt element specifies the algorithm used for signature generation and validation A SignatureMethod is implicitly given two parame ters the keying info and the output of CanonicalizationMethod The recom mendation that discusses this method is the W3C XML Signature Syntax and Processing recommendation which can be viewed at http www w3 org TR xmldsig core sec SignatureMethod Its attributes are discussed in Table 4 37 Table 4 37 Attributes of SignatureMethod Attributes of SignatureMethod Description aor The algorithm to be used for signing The default value is 9 http www w3 org 2000 09 xmldsig rsa shal DigestMethod The lt DigestMethod gt element specifies the algorithm used for generating the digest of the object to be signed The recommendation that discusses this method is the W3C XML Signature Syntax and Processing recommendation which can be viewed at http www w3 org TR xmldsig core sec DigestMethod The attributes of lt DigestMethod gt are discussed in Table 4 38 Table 4 38 Attributes of DigestMethod Attributes of DigestMethod Description Identifies the digest algorithm to be appli
435. t Language 283 284 USING THE SERVICE REGISTRY WEB CONSOLE Starting the Web Console To start the Web Console type the following URL into a web browser http hostname port soar registry thin browser jsp For example http localhost 8080 soar registry thin browser jsp If the Registry is installed on your system the hostname is localhost If the Registry is not installed on your system use the name of the system where the Registry is installed The port value is usually 8080 unless there is a port con flict The Web Console has the following main sections e Top banner where you can reset the locale end the current session and set the content language e Menu area on the left side of the screen e Registry Objects area to the right of the menu area which displays found objects e Detail area below the Registry Objects area which displays the details for any found object Note At this release the top right corner of the Web Console lists the Current User as Registry Guest In fact the user is Registry Operator that is the user identity under which all objects will be published Changing the Default Language You can change the default language for the display of two kinds of information e Web Console labels and messages e Registry content CHANGING THE DEFAULT LANGUAGE 285 Changing the Default Language for Labels and Messages The Web Console s labels and messages can be displayed in the languages li
436. t an error binding setValidateURI false binding setAccessURIC http TheCoffeeBreak com 8080 sb serviceBindings add binding Add service bindings to service service addServiceBindings serviceBindings Add service to services then add services to organization services add service org addServices services A service binding normally has 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 document you create a SpecificationLink object that refers to an Extrin sicObject For details see Storing Items in the Repository page 60 55 56 DEVELOPING CLIENTS FOR THE SERVICE REGISTRY This mechanism is different from the way you publish a specification s location to a UDDI registry for a UDDI registry you create a Concept object and then add the URL of the WSDL document to the Concept object as an ExternalLink object Saving Objects in the Registry Once you have created an object and set its attributes you publish it to the Reg istry by calling the LifeCycleManager saveObjects method or an object spe cific save method like BusinessLifeCycleManager saveOrganizations or BusinessLifeCycleManager saveServices You always publish a collection of objects not a single object The save methods return a BulkResponse object that contains the keys that i
437. t has been internationalized into several locales Contains a Collection of LocalizedString objects InternationalString The name and description of a RegistryObject are Inter nationalString objects Getter methods Regist ryOb ject getName RegistryObject getDescription Represents a unique key that identifies a RegistryObject Must be a DCE 128 UUID Universal Unique IDentifier Getter method RegistryObject getKey DEVELOPING CLIENTS FOR THE SERVICE REGISTRY Table 8 3 JAXR Object Types Used as Attributes Continued A component of an InternationalString that associates a LocalizedString String with its Locale Getter method International String getLocalizedStrings Represents a person s name A User has a PersonName Getter PersonName method User getPersonName Represents a postal address An Organization or User may have one or more PostalAddress objects Getter methods PostalAddress Organization getPostalAddress Organization Imp1 getPostalAddresses implementation specific User getPostalAddresses Represents a telephone number An Organization or a User may have one or more TelephoneNumber objects Getter meth ods Organization getTelephoneNumbers User getTelephoneNumbers TelephoneNumber Finding Objects by Name To search for objects by name you normally use a combination of find qualifiers which affect sorting and pattern matching and name patterns which specify the strings to b
438. t tree At any point client applications can call the Validator validate method on the Java content tree or any sub tree of it All JAXB Providers are required to support this operation If the client application does not set an event handler on its Validator Unmar shaller or Marshaller prior to calling the validate unmarshal or marshal methods then a default event handler will receive notification of any errors or warnings encountered The default event handler will cause the current operation to halt after encountering the first error or fatal error but will attempt to continue after receiving warnings There are three ways to handle events encountered during the unmarshal vali date and marshal operations e Use the default event handler XML SCHEMAS The default event handler will be used if you do not specify one via the setEventHandler APIs on Validator Unmarshal ler or Marshal ler e Implement and register a custom event handler Client applications that require sophisticated event processing can imple ment the ValidationEventHandler interface and register it with the Unmarshaller and or Validator e Use the ValidationEventCol lector utility For convenience a specialized event handler is provided that simply col lects any ValidationEvent objects created during the unmarshal vali date and marshal operations and returns them to the client application as a java util Col lection Validation events are handle
439. tal Signature the security configuration file would include an xwss Sign element along with a keystore alias that identifies the private key certificate associated with the sender s signature A simple client security config uration file that requires digital signatures would look like this lt xwss JAXRPCSecurity xmIns xwss http java sun com xml ns xwss config gt lt xwss Service gt lt xwss SecurityConfiguration dumpMessages true gt lt Note that in the lt Sign gt operation a Timestamp is exported in the security header and signed by default gt lt xwss Sign gt lt xwss X509Token certificateAlias xws security client gt lt xwss Sign gt lt Signature requirement No target is specified hence the soap body is expected to be signed Also by default a Timestamp is expected to be signed gt lt xwss RequireSignature gt lt xwss SecurityConfiguration gt UNDERSTANDING SECURITY CONFIGURATION FILES lt xwss Service gt lt xwss SecurityEnvironmentHandler gt com sun xml wss sample SecurityEnvironmentHandler lt xwss SecurityEnvi ronmentHand1er gt lt xwss JAXRPCSecurity gt The xwss elements can be listed sequentially so that more than one security mechanism can be applied to the SOAP message For example for a client to first sign a message and then encrypt it create an xwss element with the value Sign to do the signing first and then create an xwss element with
440. te 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 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 87 88 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 S
441. teaming 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 arbitrarily 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
442. tem properties http proxyHost and http proxyPort when you run the pro gram so that JAXR can determine the validity of the URI The following code fragment finds all organizations that have a specified Exter nalLink object ExternalLink extLink blcm createExternalLinkC http java sun com Sun Java site Collection extLinks new ArrayListQ extLinks add CextLink BulkResponse response bqm findObjectsC Organization null null null null null extLinks Collection objects response getCollection Finding Objects by Extemal Link Example For an example of finding objects by external link see the example lt INSTALL gt registry samples query external 1link src JAXRQueryByExternal Link java which searches for objects that have a specified external link The http proxyHost and http proxyPort properties are specified in the run target in the build xml file To run the example follow these steps 1 Go to the directory lt INSTALL gt registry samples query external link 2 Type the following command ant run This example is not likely to produce results unless you first run the publish object example described in Adding Classifications Example page 48 21 22 DEVELOPING CLIENTS FOR THE SERVICE REGISTRY Finding Objects by Unique Identifier Every object in the Registry has two identifiers a unique identifier also called a Key and a logical identifier Often the unique and logical identifiers
443. terSpec 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 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 281 282 JAVA XML DIGITAL SIGNATURE API Noti
444. the comp1lexType 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 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 lt See XML 1 0 2nd Edition for more information http www w3 org TR 2000 REC xml 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 CUSTOMIZE INL
445. the events and how they are created Many events are created as a side effect of some other action e Saving an object to the Registry creates an EVENT_TYPE_CREATED event e The following actions create an EVENT_TYPE_VERSIONED event e Changing an object s name or description e Adding modifying or removing a Classification ExternalIden tifier ExternalLink or Slot e For an Organization or User adding modifying or removing a PostalAddress or TelephoneNumber You can retrieve version information for an object See Retrieving the Version of an Object page 34 for details Note At this release versioning of objects is disabled All objects have a version of 1 1 You can also change the state of objects explicitly This feature may be useful in a production environment where different versions of objects exist and you wish to use some form of version control For example you can approve a version of an object for general use and deprecate an obsolete version before you remove it 65 DEVELOPING CLIENTS FOR THE SERVICE REGISTRY If you change your mind after deprecating an object you can undeprecate it You can perform these actions only on objects you own e You can approve objects by using the Li feCycleManagerImp1 approve Objects method This feature is implementation specific e You can deprecate objects by using the LifeCycleManager depreca teObjects method e You can undeprecate objects by using the LifeCycleMa
446. the service bindings and specifi cation links are also removed However the extrinsic objects associated with the specification links are not removed Creating an Extrinsic Objectasa Spec ification Link Example For an example of creating an extrinsic object as a specification link see lt INSTALL gt registry samples publish service src JAXRPub1ishSer vice java This example publishes a WSDL file to the Registry To run the example follow these steps 1 Go to the directory lt INSTALL gt registry samples publish service 2 Type the following command ant run 63 64 DEVELOPING CLIENTS FOR THE SERVICE REGISTRY Organizing Objects Within Registry Packages Registry packages allow you to group a number of logically related registry objects even if the individual member objects belong to different owners For example you could create a RegistryPackage object and add to it all objects in the Registry whose names shared a particular unique string or that all contained a Slot with the same name and value To create a RegistryPackage object call the LifeCycleManager createReg istryPackage method which takes a String or InternationalString argu ment Then call the RegistryPackage addRegistryObject or RegistryPackage addRegistryObjects method to add objects to the package For example you could create a RegistryPackage object named SunPackage RegistryPackage pkg blcm createRegistryPackage SunPackage Then
447. the value of Encrypt to encrypt after the signing Building on the previous example to add encryption to the message after the message has been signed the security config uration file would be written like this example lt xwss JAXRPCSecurity xmIns xwss http java sun com xml ns xwss config gt lt xwss Service gt lt xwss SecurityConfiguration dumpMessages true gt lt xwss Sign gt lt xwss Encrypt gt lt xwss X509Token certificateAlias slas keyReferenceType Identifier gt lt xwss Encrypt gt lt Requirements on messages received gt lt xwss RequireEncryption gt lt xwss RequireSignature gt lt xwss SecurityConfiguration gt lt xwss Service gt lt xwss SecurityEnvironmentHandler gt com sun xml wss sample SecurityEnvironmentHandler lt xwss SecurityEnvi ronmentHand1er gt lt xwss JAXRPCSecurity gt The xwss RequireSignature element present in the two examples shown is used by the client to indicate that it expects the Response to be a signed response Similarly the xwss RequireEncryption element in a client configura tion file indicates that the client expects an encrypted response In the second example a RequireEncryption and a RequireSignature element specified in 137 138 INTRODUCTION TO XML AND WEB SERVICES SECURITY that order implies that the client expects the response to be signed and then encrypted The xwss RequireSignature and xwss RequireEncryption element
448. thm 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 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 s
449. ties Ez nal parsed entities Required Sets and gets the implementation of the javax xml stream reporter J P XML Reporter Required Sets and gets the implementation of the javax xml stream resolver J XML Resolver interface Required Sets gets the implementation of the javax xml stream allocator J XMLEventAllocator interface XMLOutputFac tory 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 refer
450. tificateRequest cb getRequest locate and set certificate on request else if cb getRequest instanceof EncryptionKeyCal lback AliasSymme tricKeyRequest EncryptionKeyCal lback AliasSy mmetricKeyRequest request CEncryptionKeyCal lback A1i asSymmetricKeyRequest cb getRequest locate and set symmetric key on request else 193 194 INTRODUCTION TO XML AND WEB SERVICES SECURITY throw unsupported else if Ccallbacks i instanceof CertificateValidationCallback CertificateValidationCallback cb CertificateValidationCal lback Ycallbacks i set an X509 Certificate Validator on the callback else throw unsupported An application can also choose not to handle certain callbacks if it knows that the particular application will never require those callbacks For example if the security application only deals with signing the requests and does not deal with encryption or username tokens its handle method only needs to worry about SignatureKeyCal Iback with its associated Requests and SignatureVeri fi cationKeyCallback with its associated Requests It can then throw an UnsupportedCallbackException for any other callback The following code shows the handle method skeleton for such an application public class SecurityEnvironmentHandler implements CallbackHandler public void handle Callback callbacks throws IOException UnsupportedCallbackException for Cint i
451. tion of con tent trees by direct invocation of the appropriate factory methods Once created a content tree may be revalidated either in whole or in part at any time See Create Marshal Example page 47 for an example of using the ObjectFactory class to directly add content to a content tree J AXB Binding Framework The JAXB binding framework is implemented in three Java packages e The javax xm1 bind package defines abstract classes and interfaces that are used directly with content classes The javax xml bind package defines the Unmarshaller Validator and Marshaller classes which are auxiliary objects for providing their respective operations MORE ABOUT JAVAX XML BIND The JAXBContext class is the entry point for a Java application into the JAXB framework A JAXBContext instance manages the binding relation ship between XML element names to Java content interfaces for a JAXB implementation to be used by the unmarshal marshal and validation oper ations The javax xm1 bind package also defines a rich hierarchy of validation event and exception classes for use when marshalling or unmarshalling errors occur when constraints are violated and when other types of errors are detected e The javax xml bind util package contains utility classes that may be used by client applications to manage marshalling unmarshalling and val idation events e The javax xml bind helper package provides partial default implemen tations for s
452. tion 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 FIX COLLIDES EXAMPLE lt jxb property name zipCode gt 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 Note Many name collisions can occur because XSD Part introduces six unique symb
453. tions Demonstrating X WS Security lt JWSDP_HOME gt xws security bin Command line tools that provide specialized utilities for keystore management For more information on these read Useful XWS Security Command Line Tools This implementation of XWS Security is based on the Oasis Web Services Secu rity WSS specification which can be viewed at the following URL http docs oasis open org wss 2004 01 oasis 20040 1 wss soap message security 1 0 pdf Some of the material in this chapter assumes that you understand basic security concepts To learn more about these concepts we recommend that you explore the following resources before you begin this chapter e The Java 2 Standard Edition discussion of security which can be viewed from http java sun com j2se 1 5 0 docs guide security index html e The J2EE 1 4 Tutorial chapter titled Security which can be viewed from http java sun com j2ee 1 4 docs tutorial update2 doc index html 129 130 INTRODUCTION TO XML AND WEB SERVICES SECURITY Does XWS Sec urity Implement Any Spec ific ations XWS Security is an implementation of the Web Services Security WSS speci fication developed at OASIS WSS defines a SOAP extension providing quality of protection through message integrity message confidentiality and message authentication WSS mechanisms can be used to accommodate a wide variety of security models and encryption technologies The WSS specification defines
454. tored in the Registry The Registry has several default AdhocQueryImp1 objects that you can invoke The most useful are named FindAl1MyObjects and GetCal lersUser e FindAl1MyObjects is equivalent to the QueryManager getRegistryObjects method described in Finding Objects You Published page 22 e GetCallersUser is equivalent to the question Who am I It returns the User object associated with the client that executed the query If the caller is not logged in to the Registry this query returns the user named Registry Guest To invoke a stored query begin by using the BusinessQueryManager Imp1 findObjects method to locate the query The following code searches for the GetCallersUser query Collection namePatterns new ArrayListQ namePatterns add GetCallersUser Find objects with name GetCallersUser BulkResponse response bqm findObjectsC AdhocQuery null namePatterns null null null null Collection queries response getCollection QUERYING A REGISTRY FEDERATION 39 Then find the query string associated with the AdhocQuery and use it to create and execute a query this time using DeclarativeQueryManager methods get the first only query and invoke it Iterator qIter queries iterator if CqIter hasNextQ System out printInC No objects found else AdhocQueryImp1 aq AdhocQueryImpl qiter nextQ String qString aq toString Query query dqm createQuery qlype qString
455. try of the second PostalAddress post2 postalcode The postal code of the second PostalAddress post2 stateOrProvince The state or province of the second PostalAddress post2 street The street name of the second PostalAddress If a second Postal Address is specified the street is required it must be specified either on the command line or in a properties file post2 streetNumber The street number of the second PostalAddress post3 type The type of the third PostalAddress If a third PostalAddress is speci fied the type is required it must be specified either on the command line or in a properties file It is an arbitrary string for example Office or Home post3 city The city of the third PostalAddress post3 country The country of the third PostalAddress post3 postalcode The postal code of the third PostalAddress post3 stateOrProvince The state or province of the third PostalAddress post3 street ADD USER 83 The street name of the third PostalAddress If a third PostalAddress is specified the street is required it must be specified either on the com mand line or in a properties file post3 streetNumber The street number of the third PostalAddress phoneType telephonel type The type of the first TelephoneNumber The type is required it must be specified either on the command line or in a properties file It can have any of the following values Beeper FAX HomePhone MobilePhone or Office
456. ts java util List fixedAttributeAsConstantProperty defines the customization value fixedAttributeAsConstantProperty The value can be either true false 1 or generateIsSetMethod 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 0 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 declaration provides a way to customize the translation of XML datatypes to and from Java datatypes XML provides more datatypes than CUSTOMIZATION OVERVIEW 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
457. ttribute gt lt xs attribute name enforce type xs boolean use optional default true gt lt xs attribute name value type xs string use optional default true gt lt xs complexType gt lt xs complexType name DigestMethod_T gt lt xs attribute name algorithm type xs string use optional default http www w3 org 2000 09 xmldsig sha1 gt lt xs complexType gt 114 A XWS SECURITY FORMAL SCHEMA DEFINITION lt xs complexType name Transform_T gt lt xs sequence gt lt xs element name AlgorithmParameter type AlgorithmParameter_T minOccurs 0 maxOccurs unbounded gt lt xs sequence gt lt xs attribute name algorithm type xs string use required gt lt xs complexType gt lt xs complexType name AlgorithmParameter_T gt lt xs attribute name name type xs string use required gt lt xs attribute name value type xs string use required gt lt xs complexType gt lt xs simpleType name id_T gt lt xs restriction base xs string gt lt xs minLength value 1 gt lt xs restriction gt lt xs simpleType gt lt xs schema gt B S SXPJ AR Files There are two JAR files in the Sun Java System XML Streaming Parser SJSXP implementation of JSR 173 Streaming API for XML StAX Both of these JARs are located in the lt JWSDP_HOME gt sjsxp 1ib directory e sjsxp jar Sun implementation JAR for SJSXP e jsr173_api jar Standard API JAR for JSR 173 Th
458. ty 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 setPrefix 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 105 106 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 X
459. types of developers e Java programmers who want to use the XML Digital Signature API to gen erate and validate XML signatures 265 266 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 XML 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 267 XML Sec unty
460. u 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 only 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 103 When the XMLStreamReader cursor is over a StartElement event it reads
461. uest DecryptionKeyCal lback X509Subject KeyIdentifierBasedRequest request DecryptionKeyCallback X509Sub jectKeyIdentifierBasedRequest cb getRequest locate and set the privateKey on the request else if cb getRequest instanceof DecryptionKeyCallback X509IssuerS erialBasedRequest issuer serial request DecryptionKeyCal lback X509Issu erSerialBasedRequest request DecryptionKeyCal Iback X509 IssuerSerialBasedRequest cb getRequest locate and set the privateKey on the request else if cb getRequest instanceof DecryptionKeyCal lback X509Certi fi cateBasedRequest X509 cert request WRITING SECURITYENVIRONMENTHANDLERS DecryptionKeyCal lback X509Cert ificateBasedRequest request DecryptionKeyCal lback X509C ertificateBasedRequest cb getRequest locate and set private key on the request else if cb getRequest instanceof DecryptionKeyCal lback AliasSymmet ricKeyRequest DecryptionKeyCallback AliasSym metricKeyRequest request DecryptionKeyCallback Alia sSymmetricKeyRequest cb getRequest locate and set symmetric key on request else throw unsupported else if Ccallbacks i instanceof EncryptionKeyCallback EncryptionKeyCallback cb CEncryptionKeyCallback callbacks i if C cb getRequest instanceof EncryptionKeyCal lback Aliasx50 9CertificateRequest EncryptionKeyCal lback Aliasx50 9CertificateRequest request CEncryptionKeyCallback Alia sx509Cer
462. unique value and assigns that value to both the unique and the logical identifiers Whenever a new version of an object is created see Retrieving the Version of an Object page 34 and Changing the State of Objects in the Registry page 65 the logical identifier remains the same as the original one but the Registry generates a new unique identifier by adding a colon and the version number to the unique identifier Note At this release versioning is disabled by default The logical and unique iden tifiers remain the same after the object is modified If you plan to use your own identification scheme you can use API methods to set object identifiers In the JAXR API the unique identifier is called a Key object You can use the LifeCycleManager createKey method to create a unique identifier from a String object and you can use the Registry0b ject setKey method to set it The logical identifier is called a lid and the JAXR provider for the Registry has an implementation specific method Regis tryObjectImp1 setLid which also takes a String argument for setting this identifier The method has the following signature public void setLid java lang String lid throws JAXRException Any identifier you specify must be a valid globally unique URN Uniform Resource Name When the JAXR API generates a key for an object the key is in the form of a DCE 128 UUID Universal Unique IDentifier Creating and Using Classification Schemes and Conc
463. upply 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 represented 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 representin
464. ur 4 urn uuid abfa78d5 605e 4dbc b9ee a42e99d5f7cf Guest Registry Other Administration Tasks This section describes other tasks you may need to perform for the Registry e Backing Up and Restoring the Database Backing Up and Restoring the Database The Registry uses the Apache Derby database By default the database is located in the following directory HOME soar platform 3 data registry soar where platformis either tomcat or as8 1 To learn how to back up and restore the database consult the Apache Derby doc umentation To locate the documentation follow these steps 1 In a web browser go to the URL http incubator apache org derby 2 Click the Manuals tab 3 Locate the Server amp Admin Guide 4 Locate the sections on backing up and restoring databases 102 ADMINISTERING THE SERVICE REGISTRY A XWS Sec unty Formal Schema Defnition Formal Schema Definition This chapter shows the formal schema definition for security configuration files for XWS Security EA 2 0 More information on using security configuration files is described in Introduction to XML and Web Services Security More information on each of the schema elements is described in XWS Security Con figuration File Schema Sample applications that use these elements are described in Understanding and Running the XWS Security Sample Applica tions lt xml version 1 0 gt lt xs schema xmlIns xs http www w3 org 2001 XMLSche
465. ure 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 475yhMjSc BrIVC58w3ydbkK Ri40KbaRZ1 YeRA lt Y gt lt DSAKeyValue gt lt KeyValue gt lt KeyInfo gt XML DIGITAL SIGNATURE API EXAMPLES 273 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 xm1 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
466. urityEnvironmentHandler can be plugged into this sample to obtain the username and password at run time from a different source possibly by popping up a dialog box where the user can enter the username and password This sample s server side SecurityEnvironmentHandler makes use of a JAAS login module that takes care of authenticating the user name and password The sample demonstrates how JAAS authentication can be plugged into applications that use the XWS Security framework The source of the JAAS login module UserPassLoginModule java is located at lt JWSDP_HOME gt xws security SETTING UP FOR THE JAAS SAMPLE samples jaas sample src com sun xml wss sample directory The JAAS Validator java class in the same directory does the actual JAAS authentica tion by creating a LoginContext and calling the LoggingContext login method The UserPassLoginModule makes use of a username password XML database located at lt JWSDP_HOME gt xws security etc userpasslist xml when performing the actual authentication in its login O method Setting Up For the J AAS Sample Before the sample application will run correctly you must have completed the tasks defined in the following sections of this addendum e Setting System Properties e Setting Build Properties In addition follow the steps in this section that are specific to the jaas sample application 1 Stop the Application Server 2 Set the user name and password for the example Because
467. usly as both a producer and a consumer 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 EVENTPRODUCERCONSUMER JAVA 123 Creating an Event Producer Consumer The first step is to instantiate an event factory and then create an instance of an event producer consumer XMLEventFactory m_eventFactory XMLEventFactory newInstance public EventProducerConsumer try EventProducerConsumer ms new EventProducerConsumer XMLEventReader reader XMLInputFactory newInstance createXMLEventReader new java io FileInputStream args Q XMLEventWriter writer XMLOutputFactory newInstance createXMLEventwriter System out Creating an Iterator The next step is to create an iterator to parse the stream whi leCreader hasNextQ XMLEvent event CXMLEvent reader next Q ifCevent getEventType event CHARACTERS writer add ms getNewCharactersEvent event asCharacters else writer add eve
468. ustomize 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 enableFai 1lFastCheck false generateIsSetMethod false underscoreBinding asCharInWord gt In this example all values are set to the defaults except for col lectionType 69 USING JAXB e Setting collectionType to java util Vector specifies that all lists in 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 xsd string and having enumeration facets should be bound by default to a typesafe enum If typesafeEnumBa
469. utorial Table 2 Typographical Conventions Font Style italic Emphasis titles 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 lt italic monospace gt User selected file path components 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 Binding XML Sc hema to Java Classes with J AXB Tue Java Architecture for XML Binding JAXB provides a fast and conve nient way to bind XML schemas to Java representations making it easy for Java developers to incorporate XML data and processing functions in Java applica tions As part of this process JAXB provides methods for unmarshalling XML instance documents into Java content trees and then marshalling Java content trees back into XML instance documents What this all means is that you can leverage the flexibility of platform neutral XML data in Java applications without having to deal with or even know XML programming techniques Moreover you can take advantage of XML strengths without having to rely on heavyweight complex XML processing models like SAX or DOM JAXB hides the details and gets rid of the extraneous relation ships in SAX and DOM
470. vailable in this release simple This sample application lets you plug in different client and server side configurations describing security settings This example has support for digital signatures XML encryption decryption and username token veri fication This example allows and demonstrates combinations of these basic security mechanisms through configuration files The section Simple Security Configurations Sample Application provides examples and descriptions of configuration files used in the sample application along with instruc tions for compiling and running the application api sample This sample application shows how to use the XWS Security 2 0 APIs in a stand alone mode This sample defines the XWSSProcessor interface which is used to insulate the API user from changes that may occur in future releases of the API and provides an implementation for it The Client java file uses the XWSSProcessor APIs to secure a SOAP mes sage The section XWS Security APIs Sample Application provides further description of the sample application along with instructions for compil ing and running the application jaas sample This sample demonstrates how to plug in a JAAS LoginModule for user name password authentication Read more about JAAS at http java sun com products jaas The section JAAS Sample Application provides fur ther description of the sample application along with instructions for compiling and running the application
471. vent 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 boolean 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 3 2 lists the thirteen XMLEvent types defined in the event iterator API Table 3 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 94 STREAMING API FOR XML Table 3 2 XMLEvent Types Continued Event Type Chara
472. vent 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 Contents About This Tutorial 0 eX Who Should Use This Tutorial xi Prerequisites xi How to U
473. ver mycompany com The proxy port is the port on which the proxy host is running for example 8080 4 Save and exit the build properties file Simple Securty Configurations Sample Application The simple sample application is a fully developed sample application that demonstrates various configurations that can be used to exercise XWS Security framework code To change the type of security that is being used for the client and or the server simply modify two properties in the build properties file for the example The types of security configurations possible in this example include XML Digital Signature XML Encryption UserNameToken verification and combinations thereof This example allows and demonstrates combinations 211 212 UNDERSTANDING AND RUNNING THE XWS SECURITY SAMPLE APPLICATIONS of these basic security mechanisms through the specification of the appropriate security configuration files The application prints out both the client and server request and response SOAP messages The output from the server may be viewed in the appropriate con tainer s log file The output from the client is sent to stdout or whichever stream is used by the configured log handler Messages are logged at the INFO level In this example server side code is found in the simple server src simple directory Client side code is found in the simple client src simple direc tory The asant or ant targets build objects under the build s
474. version 1 0 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 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 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 FIX COLLIDES EXAMPLE 81 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 Relev
475. vl xml e str_transform xml str_transform xml Note The configuration files strid xm1 and no_security xm1 have syntax errors and should not be used Remember when using the XWS Security APIs to secure stand alone applica tion we will use configuration files that start with lt xwss SecurityConfigura tion gt as the root element as opposed to the other XWS Security samples that are based on JAX RPC and use lt xwss JAXRPCSecurity gt as the root element Encrypting the SOAP Message The security configuration files encryptv1l xm1 and encryptv2 xm1 enable the following tasks e Client encrypts an outbound SOAPMessage and sends it e Client verifies that the inbound SOAPMessage is encrypted THE API SAMPLE SECURITY CONFIGURATION FILES 237 The encryptv1 xm1 file looks like this lt xwss SecurityConfiguration dumpMessages true xmIns xwss http java sun com xml ns xwss config gt lt xwss Encrypt gt lt xwss X509Token certificateAlias slas gt lt xwss Encrypt gt lt xwss SecurityConfiguration gt The encryptv2 xm1 file does the same thing but specifies the following e The public key encryption algorithm to be used for encrypting and decrypting keys e The encryption algorithm to be applied to the cipher data e Specifically identifies the type of encrypted structure being described It looks like this lt XWSS SecurityConfiguration dumpMessages true xmIns xwss http java sun com xml ns xwss co
476. writer directory Cursor Writer java 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 createXMLStreamWriter new FileWriter fileName xtw writeComment all elements here are explicitly in the HTML namespace Xtw writeStartDocument C utf 8 1 0 xtw setPrefixC 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 writeEndElement xtw writeStartElementC http ww w3 org TR REC htm140 body xtw writeStartElementC http www w3 org TR REC htm140 p Xtw writeCharacters Moved to xtw writeStartElementC http www w3 org TR REC htm140 a xtw xtw xtw writeEndElement xtw writeEndElement xtw flushQ xtw xtw xtw
477. wss SecurityConfiguration dumpMessages true gt lt xwss Requirelimestamp gt lt xwss RequireSignature requireTimestamp false gt lt xwss SAMLAssertion type HOK gt 254 UNDERSTANDING AND RUNNING THE XWS SECURITY SAMPLE APPLICATIONS lt xwss Target type qname gt http schemas xmlsoap org soap envelope Body lt xwss Target gt lt xwss RequireSignature gt lt xwss SecurityConfiguration gt lt xwss Service gt lt xwss SecurityEnvironmentHandler gt sample SecurityEnvironmentHandler lt xwss SecurityEnvi ronmentHand1er gt lt xwss JAXRPCSecurity gt Running the SAML Interop Sample To run the samlinterop sample application follow these steps 1 Complete the tasks defined in the following sections of this addendum Setting System Properties Configuring a JCE Provider Setting Build Properties 2 Start the selected container and make sure the server is running To start the Application Server a From a Unix machine enter the following command from a terminal window asadmin start domain domain1 b From a Windows machine choose Start gt Programs Sun Microsystems J2EE 1 4 Start Default Server 3 Modify the build properties file to set up the security configuration that you want to run for the client and or server To do this remove the com ment character from beside the client and server configuration pair to be used and make sure the other security configuration files
478. x to pin this object in place while you perform another search You can then relate two different objects by selecting both objects Viewing Object Details In the search results table click the Details link for an object to open the Details area immediately below the Registry Objects area 291 292 USING THE SERVICE REGISTRY WEB CONSOLE This section has a row of buttons and a row of tabs e The buttons are Save Approve Deprecate Undeprecate and Delete The buttons represent actions you can perform on the object e The tabs represent the object s attributes The tabs you see vary depending on the object type Table 7 4 describes the tabs and the objects they apply to Table 7 4 Attribute Tabs in the Details Area Object Detail All objects Classifications All objects Externalldentifiers All objects Associations All objects ExternalLinks All objects Audit Trail All objects PostalAddresses Organization User TelephoneNumbers Organization User EmailAddresses Organization User Users Organization Organizations Organization ServiceBindings Service SpecificationLinks ServiceBinding ChildConcepts Click a tab to find out if the object has any values for the attribute If it does click the Details link for the attribute value to open a web browser window with ClassificationScheme the details for the attribute
479. xml1 stream events Characters class javax xml stream events Comment class javax xml stream events DTD class javax xml stream events EndDocument class javax xml stream events EndElement class javax xml stream events EntityDeclaration class javax xml stream events EntityReference class javax xml stream events Namespace class javax xml stream events NotationDeclaration class javax xml stream events ProcessingInstruction class javax xml stream events StartDocument class javax xml stream events StartElement class javax xml1 stream events XMLEvent class javax xml stream uti1l EventReaderDelegate class javax xml1 stream util StreamReaderDelegate class javax xml1 stream uti1l XMLEventAllocator class javax xm1 stream uti1 XMLEventConsumer class Symbols percent sign wildcard for searches 288 wildcard in JAXR queries 14 _ underscore wildcard for searches 288 wildcard in JAXR queries 15 A add association command 76 add user command 78 addAssociation method Regis tryObject interface 58 addChi 1dConcept method Classi ficationScheme interface 46 addChi 1dConcept method Concept interface 46 addChildOrganization method Organization interface 52 addChildOrganizations method Organization interface 52 addClassification method Reg istryObject interface 48 addRegistryObject method Reg istryPackage interface 64 addRegistryObjects method Reg istryPackage interface 64 addServiceBindings method Ser Index vice
480. xtw MYSTREAMFILTER JAVA 119 writeAttributeC href http frob com writeCharacters here writeEndElement writeEndElement writeEndDocument 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 www w3 org TR REC htm140 gt lt html head gt lt html title gt Frobnostication lt html 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 EventParse java sample the namespace prefix is added to both the opening and closing 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 MySteamFilterjava Located in the lt JWSDP_HOME gt sjsxp samples filter directory MyStream Filter java demonstrates how to use the StAX stream filter API to filter out events not needed by your application In this
481. y 68 DEVELOPING CLIENTS FOR THE SERVICE REGISTRY AuditableEvent and Association objects are not always deleted when the objects associated with them are deleted You may find that as you use the Regis try a large number of these objects accumulates Removing Objects from the Registry Example For an example of deleting an object from the Registry see lt INSTALL gt regis try samples delete object src JAXRDelete java This example deletes the object whose unique identifier you specify To run the example follow these steps 1 Go to the directory lt INSTALL gt registry samples delete object 2 Type the following command ant run Did id_string 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 http java sun com xm1 jaxr e ebXML http www ebxml org e Java 2 Platform Enterprise Edition http java sun com j2ee e Java Technology and XML http java sun com xm1 e Java Technology and Web Services http java sun com webservices 9 Administenng the Service Registry Tiss chapter describes how to use the Administration Tool the Admin Tool for the Service Registry This chapter contains the following sections e About the Admin Tool e Starting the Admin Tool e Using the Admin Tool e Using Admin Tool Commands e Other Administration Tasks
482. y XMLInputFactory factory XMLInptuFactory newlInstance factory setProperty report cdata event Boolean TRUE SJ SXP Factories Implementation Most applications do not need to know the factory implementation class name Just adding the sjsxp jar file to the classpath is sufficient for most applications because sjsxp jar supplies the factory implementation classname for various SJSXP properties under the META INF services directory for example javax xml stream XMLInputFactory javax xml stream XMLOutputFac tory and javax xm stream XMLEventFactory which is the third step of a lookup operation when an application asks for the factory instance See the java doc for the XMLInputFactory newInstance 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
483. y specify the proxy host in your web browser settings The proxy port has the value 8080 which is the usual one Change this string if your proxy uses a different port Your entries usually follow this pattern proxyHost proxyhost mydomain proxyPort 8080 DEVELOPING CLIENTS FOR THE SERVICE REGISTRY Edit the file build properties tomcat as follows 1 2 Set the property tomcat home to the directory where you installed the Java WSDP Set the properties proxyHost and proxyPort to specify your own proxy settings The proxy host is the system on your network through which you access the Internet You usually specify the proxy host in your web browser settings The proxy port has the value 8080 which is the usual one Change this string if your proxy uses a different port Your entries usually follow this pattern proxyHost proxyhost mydomain proxyPort 8080 Copy the files as follows 1 2 Copy the file you edited build properties tomcat or build proper ties as to build properties Copy the corresponding targets xm1 file targets xm tomcat or tar gets xml as to targets xml Edit the file JAXRExamples properties as follows 1 Edit the properties query url and publish url to specify the URL of the Registry The file provides a default setting of localhost 8080 for the host and port but you may need to change this to another host or port if the Registry is installed on a remote server or at a non
484. yByCountryClassification java The first example searches for objects that use the canonical classification scheme InvocationMode1l while the other example searches for organizations that use a geographical classification To run the examples follow these steps 1 Go to the directory lt INSTALL gt registry samples query classifica tion 2 Type either of the following commands ant query class ant query geo These examples are likely to produce results only after you have published an object that uses the specified classification for example the one in Adding Clas sifications Example page 48 causes the query geo target to return an object 19 20 DEVELOPING CLIENTS FOR THE SERVICE REGISTRY Finding Objects by Extemal Identifier Finding objects by external identifier is similar to finding objects by classifica tion You first find the classification scheme then create an Externalidenti fier object to be used as an argument to the BusinessQueryManagerImp1 findObjects method or another finder method The following code fragment finds all registry objects that contain the Sun Microsystems stock ticker symbol as an external identifier The sample database included with the Registry does not have any external classification schemes so you would have to create one named NASDAQ for this example to work See Add ing External Identifiers to Objects page 49 for details on how to do this The collection of external identifiers

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