Results 1 to 1 of 1
  1. #1
    Java Exam is offline Member
    Join Date
    Dec 2011
    Posts
    64
    Rep Power
    0

    Default Tutorial:In Depth Look at JAXR for the Web Service Developer Exam

    In this article, we will look at JAXR for providing access to UDDI registries used for Web services. We will look at how JAXR 2.0 is used for discovering, browsing and accessing Web services registered with UDDI registries. This is part of a larger series of articles to help you prepare for the web service developer exam. You can review the article on UDDI, “Tutorial:In Depth Look at UDDI for the Web Service Developer Exam” if needed.

    What is JAXR

    JAXR stands for Java API for XML Registries and is a client-side API for accessing different kinds of XML-based business registries. It is used predominantly for UDDI and ebXML registries. The data model of the JAXR API aligns closely to the ebXML concepts and terminology, but it still works well for UDDI. The JAXR Architecture is shown in the figure below:

    Tutorial:In Depth Look at JAXR for the Web Service Developer Exam-b12-jaxrarchitecture.jpg
    Figure: JAXR Architecture

    Similar to JDBC which provides a vendor-neutral API for accessing any type of relational database, JAXR provides a vendor-neutral API for accessing any ebXML or UDDI registry. Java EE 5 vendors provide their own implementations of the JAXR API for accessing ebXML, UDDI, or other types of XML registry systems.

    The JAXR API has two levels of conformance levels:
    • Level 0 - provides fewer features and is intended for UDDI registries, which are less flexible than ebXML but more popular
    • Level 1 - provides a richer API that is designed for accessing ebXML registries.

    As we are helping you to prepare for the Web Service Developer exam, and the WS-I Basic Profile 1.1 sanctions the use of UDDI, but not ebXML, we will focus on only JAXR Level 0, the UDDI-compliant aspect of the API.

    There are two interdependent packages in JAXR: The Query and Life Cycle API (javax.xml.registry) and the Information Model (javax.xml.registry.infomodel). The Query and Life Cycle API supports the UDDI Inquiry and Publishing APIs respectively. The Information Model provides business- and technical-object views that correspond to UDDI data structures (i.e. businessEntity, bindingTemplate, tModel, etc).

    JAXR is very useful when you need to build a UDDI browsing tool or for supporting the actual SOAP communications between the browser and the UDDI registry. JAXR is also useful for implementing failover mechanisms to gracefully handle the problem of a Web service endpoint that is no longer available. You can use the JAXR API to look up the Web service in UDDI and determine whether an alternative access point is offered. A lot of the grunt work for developers to communicate with a UDDI registry is hidden behind JAXR's APIs and infomodel. This leaves the developers to work with business objects and technical objects representing the organizations, services, classification systems, etc without need to think about SOAP messaging.

    Testing a UDDI Test Registry

    There are a number of UDDI registry that are public available called the UDDI Business Registry (UBR) that anyone can use free of charge. The UBR can be accessed from four different operator sites hosted by originally Microsoft, IBM, SAP, and NTT. Microsoft has since dropped out. IBM will be discontinuing at some point in the future. The three remaining organizations regularly synchronize the UDDI registry entries so that an entry made on one system is replicated, after a period of time, on the other three. You also have access to a test registry from all of the UBR operator sites except NTT. All four organizations offer a production registry.

    You can access the IBM test registry by going to http://uddi.ibm.com/testregistry/registry.html. Once you have registered, you can test your web services there. The registration will give you rights to create business entries in the production registry as well, but focus on the test directory until you feel comfortable with JAXR and ready to create a real-world entry in the UBR.

    If you need access to JAXR, the best bet is that your Java EE 5 application server will include a JAXR provider. Once you have located it, include the provider JAR in your classpath.

    Connecting to a UDDI Registry

    In order to connect to a UDDI registry with JAXR you need to obtain a ConnectionFactory, configure its connection properties, and then request a Connection object. Again this is similar to JDBC as we mentioned before. The Java EE 5 application servers may take care of some of this work, such as configuration, automatically. This all depends on the vendor.

    In a standalone application you have to configure the ConnectionFactory in your code. In the listing below we show how to connect to a the IBM Test Registry from a non-Java EE 5 client.

    Java Code: Connecting to a UDDI Registry
    package com.acme.jaxr;
    import javax.xml.registry.ConnectionFactory;
    import javax.xml.registry.Connection;
    import javax.xml.registry.RegistryService;
    import javax.xml.registry.BusinessLifeCycleManager;
    import javax.xml.registry.infomodel.Organization;
    import javax.xml.registry.infomodel.InternationalString;
    import javax.xml.registry.JAXRException;
    import java.net.PasswordAuthentication;
    import java.util.Properties;
    import java.util.Set;
    import java.util.HashSet;
    
    public class JaxrForConnection {
      public static void main(String [] args) throws JAXRException {
        // Extract parameters.
        String userName = args[0];
        String password = args[1];
    
        // Connect to UDDI registry and authenticate.
        Connection connection = connectToRegistry(userName,password);
    
        // Close connection.
        connection.close();
      }
      public static Connection connectToRegistry(String userName,
                                                 String password)
      throws JAXRException {
        // Create a ConnectionFactory.
        ConnectionFactory factory = ConnectionFactory.newInstance();
    
        // Configure the ConnectionFactory.
        Properties props = new Properties();
        props.setProperty("javax.xml.registry.lifeCycleManagerURL",
                          "https://uddi.ibm.com/testregistry/publishapi");
        props.setProperty("javax.xml.registry.queryManagerURL",
                          "http://uddi.ibm.com/testregistry/inquiryapi");
        props.setProperty("javax.xml.registry.security.authenticationMethod",
                        "UDDI_GET_AUTHTOKEN");
        factory.setProperties(props);
    
        // Connect to UDDI test registry.
        Connection connection = factory.createConnection();
    
        // Authenticate (log in) to the Publishing endpoint.
        PasswordAuthentication credential =
          new PasswordAuthentication(userName, password.toCharArray());
        Set credentials = new HashSet();
        credentials.add(credential);
        connection.setCredentials(credentials);
    
        return connection;
      }
    }
    In the listing, we first create a ConnectionFactory, then configure it and connect to a UDDI registry by passing authentication information in order to authenticate the user. We have made this part reusable by encapsulating it into the connectToRegistry() method.

    Once the JAXR library is installed and the classpath set up, you can run the program. If you don't have any error messages, then you have succeeded. Otherwise, the program with throw a JAXRException and display the error on the output screen.

    Obtaining a ConnectionFactory

    As we previously mentioned, connecting to a UDDI registry is straightforward for both Java EE 5 and non-Java EE 5 applications. The first task is to use ConnectionFactory.newInstance() to create a ConnectionFactory:

    Java Code: Creatng ConnectionFactory
    // Create a ConnectionFactory.
    ConnectionFactory factory = ConnectionFactory.newInstance();
    We are here assuming in the listing that you’re using a JAXR reference implementation or have specified a special JAXR system property naming the JAXR ConnectionFactory implementation class. As all vendors‘ implementation of the ConnectionFactory is unique, If you don’t use the JAXR RI, you'll need to specify the following system property, in one of following ways:

    Java Code: Specification of System Property for JAXR
    javax.xml.registry.ConnectionFactoryClass =vendors_connectionfactory_class
    You can do this in Java by using the java.lang.System.setProperty() method, or by doing the following at the command line:

    XML Code: Obtaining a Connection Factory
    java -Djavax.xml.registry.ConnectionFactoryClass=some_class_name com.acme.jaxr
    .MyJaxr  UserID Password
    It’s possible also to add the property to your operating system's registry before opening a command window. If you’re using the reference implementation of JAXR, there is no need to set the ConnectionFactoryClass system property.

    Configuring the ConnectionFactory

    You need to configure the connection URLs before using a ConnectionFactory to create a connection. The two sets of Web service operations supported by UDDI registries are the following:
    • Inquiry - used to search and navigate the UDDI directory
    • Publishing - used to add, modify, and delete information in the registry.

    Every UBR operator sites have their own endpoints for both Inquiry and Publishing. They are separate URLs and three of them have different URLs for testing and production. The list below shows the UDDI.org listed sites of all remaining UBR operator sites for Inquiry and Publishing URLs:

    IBM

    UBR Node
    Home page = http://uddi.ibm.com/
    Inquiry API = http://uddi.ibm.com/ubr/inquiryapi
    Publishing API = https://uddi.ibm.com/ubr/publishapi

    Test Node
    Home page = http://uddi.ibm.com/testregistry/registry.html
    Inquiry API = http://uddi.ibm.com/testregistry/inquiryapi
    Publishing API = https://uddi.ibm.com/testregistry/publishapi

    SAP

    UBR Node
    Home page = http://uddi.sap.com/
    Inquiry API = http://uddi.sap.com/uddi/api/inquiry
    Publishing API = https://uddi.sap.com/uddi/api/publish

    Test Node
    Home page = http://udditest.sap.com/
    Inquiry API = http://udditest.sap.com/UDDI/api/inquiry
    Publishing API = https://udditest.sap.com/UDDI/api/publish

    NTT

    UBR Node
    Home page = http://www.ntt.com/uddi/
    Inquiry API = http://www.uddi.ne.jp/ubr/inquiryapi
    Publishing API = https://www.uddi.ne.jp/ubr/publishapi

    Note that all of the operator sites provide both a test node UDDI registry as well as a real-world UBR node. The one exception is NTT. Only do development work on the test node. Use the UBR node only for production ready system. To use the JAXR ConnectionFactory you need to configure its Inquiry and Publishing URLs in order that the JAXR provider knows where to send Inquiry and Publishing SOAP messages. In the listing below we show how to configure the Inquiry and Publishing URLs to connect to IBM's test node:

    Java Code: Configure the ConnectionFactory
    Properties props = new Properties();
    props.setProperty("javax.xml.registry.lifeCycleManagerURL",
                      "https://uddi.ibm.com/testregistry/publishapi");
    props.setProperty("javax.xml.registry.queryManagerURL",
                      "http://uddi.ibm.com/testregistry/inquiryapi");
    props.setProperty("javax.xml.registry.security.authenticationMethod",
                      "UDDI_GET_AUTHTOKEN");
    factory.setProperties(props);
    We use standard properties that are supported by all JAXR vendors to configure the ConnectionFactory. There are a number of different standard properties you can use to configure the ConnectionFactory. These are shown in the table below:

    Tutorial:In Depth Look at JAXR for the Web Service Developer Exam-b12-jaxrstandardconfigurationproperties.jpg
    Table: JAXR Standard Configuration Properties

    Table shows that the lifeCycleManagerURL and queryManagerURL properties identify URLs of the Publishing and Inquiry Web services. The UBR registries use UDDI_GET_AUTHTOKEN for the property authenticationMethod to indicate that an authorization token is to be passed with every Publishing operation The maxRows property limits the size of your result sets. The postalAddressScheme property sets the default structure of address values (i.e. U.S. address, Canadian address, etc).

    Connecting to the UDDI Registry

    Once the ConnectionFactory is configured, you can use it to create a Connection object. This represents a virtual connection to the UDDI directory since HTTP is a “connectionless protocol because TCP/IP does not maintain connections between requests. You then use UDDI SOAP messages over HTTP for inquiry and HTTPS for publishing. The inquiry SOAP messages are sent to the Inquiry URL while the publishing messages are sent to the Publishing URL. The listing below shows how to create a Connection from a ConnectionFactory:

    Java Code: Connect to UDDI test registry
    Connection connection = factory.createConnection();
    The listing demonstrates that it is very simple to create a connection. It is also possible to create a FederatedConnection. A FederatedConnection is used to query several different registries at the same time. In order to create a FederatedConnection, you create two or more regular JAXR connections, then use the Connection objects to create a Federated Connection. The listing below shows how to create a FederatedConnection:

    Java Code: Creation of a FederatedConnection
    Set connections = HashSet();
    Connection con1 = factory1.createConnection();
    connections.add(con1);
    Connection con2 = factory2.createConnection();
    connections.add(con2);
    FederatedConnection federatedCon = factory3.createFederatedConnection( connections);
    Once you have a created a FederatedConnection, the search operations will be executed against all of the registries represented by the FederatedConnection all. In other words, you will be searching multiple registries at once. This an optional feature that not all vendors support. Also developers rarely need to send the same query to multiple registries.

    Authenticating to a UDDI Registry

    Any user can query the UBR at any operator site, but only registered and authenticated users can publish data to the UBR. To register you need to browse the UDDI Web site of the operator. The requirements are different requirements for registering with each operator site. All request basic information about yourself and you will need to provide a username and password. You the URLs for the operator sites shown before in order to register.

    Once you are registered with a UBR operator, you can publish information to the UDDI registry. We have used the IBM's test registry for this article. Once you become familiarized with JAXR, it is easy to move to any one of the other operator sites or even to a private UDDI registry.

    When you’re using JAXR with a Java EE 5 component, it’s possible your Java EE 5 application server is configured to authenticate an individual automatically. Your Java EE 5 application server supports container-managed authentication with the JAXR provider. In order to execute publishing operations such as adding, updating, and removing information in the UDDI directory, first you authenticate to the registry. The listing shows how to authenticate using a user name and password:

    Java Code: Authenticate to the UDDI registry
    PasswordAuthentication credential =
            new PasswordAuthentication(userName, password.toCharArray());
    Set credentials = new HashSet();
    credentials.add(credential);
    connection.setCredentials(credentials);
    The PasswordAuthentication class is part of the Java Networking package (java.net) that provides a wrapper for the user name and password. In Private UDDI registries the authentication required might be of a different nature such as X.509 certificates. In this case, you would need to pass an instance of javax .security.auth.x500.X500PrivateCredential class, which is part of the Java Authentication and Authorization Service (JAAS) API. The listing below shows you how you can authenticate using an X.509 certificate:

    Java Code: Authenticate using X.509 Certificate
    KeyStore ks = KeyStore.getInstance("JKS");
    X509Certificate certificate = (X509Certificate)
                    keyStore.getCertificate( userName );
    PrivateKey privateKey = (PrivateKey)
                    keyStore.getKey( userName, password.toCharArray());
    X500PrivateCredential x500Credential =
                    new X500PrivateCredential(certificate, privateKey);
    Set credentials = new HashSet();
    credentials.add(x500Credential);
    connection.setCredentials(credentials);
    Obtaining a JAXR Connection in Java EE 5

    For Java EE 5 components, you will need to access a JAXR ConnectionFactory from the component's JNDI Environment Naming Context (JNDI ENC). The JNDI ENC is used to access JAX-RPC endpoints, JDBC, JMS, Java EE 5 Connectors, EJBs, and any other resources. The following code snippet shows how a Java EE 5 component would access a JAXR ConnectionFactory from the JNDI ENC:

    Java Code: Access JAXR ConnectionFactory
    InitialContext jndiEnc = new InitialContext();
    ConnectionFactory factory = (ConnectionFactory)
       jndiEnc.lookup("java:comp/env/jaxr/UddiRegistry");
    Connection connection = factory.createConnection();
    ...
    A component developer would view accessing a UDDI connection to be easier in Java EE 5 clients than in standalone applications since the connection properties for Publishing and Inquiry APIs may not need to be set or at times doesn’t require explicit authentication. The work is done instead by the Java EE 5 container system automatically. Also you need not close your connection explicitly since the Java EE 5 container manages the JAXR Connection objects automatically. In any respect, it is always good practice to close your connections irrespective of whether the container will close them for you.

    To use JAXR in Java EE 5 you'll need to configure JAXR as a resource in your component's deployment descriptor. The following listing shows deployment descriptor elements used to configure JAXR for use with a JAX-RPC service endpoint:

    XML Code: JAXR Resource Configuration in Deployment Descriptor
    <web-app>
        <display-name>MyJavaServiceEndpoint</display-name>
        ...
        <resource-ref>
             <res-ref-name>jaxr/UddiRegistry</res-ref-name>
             <res-type>javax.xml.registry.ConnectionFactory</res-type>
             <res-auth>Container</res-auth>
        </resource-ref>
       ...
    The configuration of JAXR is the same as for other resources configured for Java EE 5 components. At deployment time the deployer will map the configuration properties for authentication and access to the Publishing and Inquiry APIs. The Java EE 5 container authenticates you automatically every time you use JAXR to access the Publishing API of a UDDI registry. The configuration of the information by the deployer differs from vendor to vendor since the interface for configuration of the properties in Java EE 5 is not specified.
    It is only the manner in which you create a ConnectionFactory and configure it which is the only difference between using JAXR from Java EE 5 components and from non-Java EE 5 components.

    Using the RegistryService and BusinessLifeCycleManager

    After we have established the connection and you are authenticated with the UDDI registry, now you can access the UDDI registry. What you use to do this is the RegistryService object. This object represents the UDDI registry. You use it to get a reference to the BusinessLife CycleManager object in order to add, modify, and delete information in the registry. The listing below shows hot to get the Registry Service and BusinessLifeCycleManager objects, and then create and save an Organization object in the UDDI registry.

    Java Code: Creating a New Organization object
    package com.acme.jaxr;
    import javax.xml.registry.ConnectionFactory;
    import javax.xml.registry.Connection;
    import javax.xml.registry.RegistryService;
    import javax.xml.registry.BusinessLifeCycleManager;
    import javax.xml.registry.infomodel.Organization;
    import javax.xml.registry.infomodel.InternationalString;
    import javax.xml.registry.JAXRException;
    import javax.xml.registry.JAXRResponse;
    import javax.xml.registry.BulkResponse;
    import java.net.PasswordAuthentication;
    import java.util.Properties;
    import java.util.Set;
    import java.util.HashSet;
    import java.util.Iterator;
    
    public class JaxrForNewOrg {
      public static void main(String [] args) throws JAXRException {
        // Extract parameters.
        String companyName = args[0];
        String userName = args[1];
        String password = args[2];
        // Connect to the UDDI registry and authenticate.
        Connection connection = connectToRegistry(userName,password);
    
        // Access the RegistryService and BusinessLifeCycle objects.
        RegistryService registry = connection.getRegistryService();
        BusinessLifeCycleManager lifeCycleMngr =
                                 registry.getBusinessLifeCycleManager();
    
        // Create an Organization object and assign it a name.
        Organization myOrganization =
                     lifeCycleMngr.createOrganization(companyName);
    
        // Save the Organization to the UDDI directory.
        Set organizationSet = new HashSet();
        organizationSet.add(myOrganization);
        BulkResponse response =
                     lifeCycleMngr.saveOrganizations(organizationSet);
    
        // Check for registry exceptions.
        doExceptions(response);
    
        // Close connection.
        connection.close();
      }
    
      public static void doExceptions(BulkResponse rspns)
      throws JAXRException {
        if(rspns.getStatus()==JAXRResponse.STATUS_SUCCESS){
          System.out.println("\nProgram Complete: No problems reported!");
        }else {
          Iterator exceptions = rspns.getExceptions().iterator();
          while(exceptions.hasNext()){
            Exception je = (Exception)exceptions.next();
            System.out.println("\n***** BulkResponse Exceptions *****\n\n");
            je.printStackTrace();
            System.out.println("\n***********************************");
          }
        }
      }
    
      public static Connection connectToRegistry(String userName,
                                                 String password)
      throws JAXRException {
         /* The code for this method is omitted for brevity. See
            Listing 16-1 for the implementation.*/
      }
    }
    You can run this example if you choose by doing the following:

    Java Code: Running JaxrForNewOrg
    java com.acme.jaxr.JaxrForNewOrg organizationName userName password
    The organization name cannot include spaces as in the command line a space is interpreted as a parameter separator. After running it, check to see whether your Organization was added to the UDDI registry by logging in to IBM's test registry and searching for the company you created. Keep track of the name you have assigned the organization since we will later delete the organization entry using the Web interface, to help keep the test registry as clean as possible.

    The RegistryService

    The principal interface in JAXR API is the RegistryService. It represents the entire UDDI registry. Once you have the JAXR Connection object, you can access it as shown in the JaxrForNewOrg listing:

    Java Code: Access the RegistryService and BusinessLifeCycle objects
    RegistryService registry = connection.getRegistryService();
    The RegistryService defines methods that allow you to access different capabilities offered by a registry. There are methods that are used with and without UDDI. Below is the RegistryService interface definition:

    Java Code: The javax.xml.registry.RegistryService Interface
    package javax.xml.registry;
    import java.util.*;
    import javax.xml.registry.infomodel.*;
    
    public interface RegistryService {
       // Returns the CapabilityProfile for the JAXR provider.
       CapabilityProfile getCapabilityProfile() throws JAXRException;
    
       // Returns the BusinessLifeCycleManager object.
       BusinessLifeCycleManager getBusinessLifeCycleManager()
         throws JAXRException;
    
       // Returns the BusinessQueryManager object.
       BusinessQueryManager getBusinessQueryManager() throws JAXRException;
    
       // This method is not applicable to UDDI.
       BulkResponse getBulkResponse(String requestId)
         throws InvalidRequestException, JAXRException;
    
       // Get the default postal scheme for PostalAddress.
       public ClassificationScheme getDefaultPostalScheme()  throws JAXRException;
    
       // This method sends an XML request in a registry-specific format.
       public String makeRegistrySpecificRequest(String request)
         throws JAXRException;
    }
    The getCapabilityProfile() method returns a CapabilityProfile object that indicates the JAXR specification version and the capability level (Level 0 or Level 1) of the JAXR provider.
    The getBusinessLifeCycleManager() method returns a BusinessLife CycleManager object that can be used to add, modify, or delete information in the UDDI registry.
    The getBusinessQueryManager() method returns a BusinessQuery Manager object that is used to search for and retrieve information from the UDDI registry.
    The getBulkResponse() method is designed to access a response when asynchronous messaging is used. As UDDI uses only Request/Response-style messaging, this is not a method applicable to UDDI.
    The makeRegistrySpecificRequest() method allows you to send an explicit XML document fragment in a SOAP message to the UDDI registry. This can be useful if the XML is already generated or if some facet of the request cannot be expressed using the JAXR API.

    The UDDI Inquiry API

    The RegistryService defines a method named getDeclarativeQueryManager() that facilitates sending dynamic queries to the registry using SQL or OQL or some other declarative language. This is a JAXR Level 1 method that is not supported by UDDI because UDDI since it doesn’t define a declarative query language.

    Functionality of the BusinessLifeCycleManager

    In discussing the functionality of the BusinessLifeCycleManager, it is necessary to include the functionality of the LifeCycleManager. This is the superinterface for the BusinessLifeCycleManager. This is because many of the methods defined by LifeCycleManager are used to manufacture in-memory instances of JAXR information objects. The methods defined by the BusinessLifeCycleManager subtype are used to save, update, and delete information in the UDDI registry. We obtain a reference to the BusinessLifeCycleManager via the RegistryService object. This was shown in the listing for JaxrForNewOrg. We highlight that part of the listing below:

    Java Code: Access the RegistryService and BusinessLifeCycle objects
    RegistryService registry = connection.getRegistryService();
    BusinessLifeCycleManager lifeCycleMngr =
                             registry.getBusinessLifeCycleManager();
    The next two sections examine the functionality defined by the LifeCycle Manager and the BusinessLifeCycleManager. Keep in mind that when you use a reference to a BusinessLifeCycleManager, you are also using a reference to a LifeCycleManager.

    The LifeCycleManager

    The LifeCycleManager interface defines factory methods used for creating instances of every type of information object in the UDDI. This goes from Organization to PersonName. In the listing for JaxrForNewOrg, we create an Organization instance using one of the methods defined by the LifeCycleManager interface. This part of the listing is shown again below:

    Java Code: Access the RegistryService and BusinessLifeCycle Objects
    RegistryService registry = connection.getRegistryService();
    BusinessLifeCycleManager lifeCycleMngr =
                             registry.getBusinessLifeCycleManager();
    
    // Create an Organization object and assign it a name.
    Organization myOrganization =
                 lifeCycleMngr.createOrganization(companyName);
    Whenever an information object such as an Organization, Service, or User is created by one of the LifeCycleManager factory methods, the factory methods only instantiate the object type. You need to use the appropriate saveXXX() method defined by the BusinessLifeCycleManager since none of the object are automatically added to the UDDI registry.

    It is very convenient to be able to build an in-memory graph of JAXR objects and then save the entire graph to the registry with a single call. This allows you to manipulate an entry without the latency of SOAP calls. Once your entry is in the state that you desire with the relevant information, you can save it to the UDDI registry. The developer need to make only one call to the registry, when the saveXXX() method is invoked. The JAXR provider could be using a number of different SOAP messages to update UDDI information, but that work is all done automatically when you call saveXXX(). In the listing below, we provide the LifeCycleManager interface:

    Java Code: The javax.xml.registry.LifeCycleManager Interface
    package javax.xml.registry;
    import java.util.*;
    import javax.xml.registry.infomodel.*;
    
    public interface LifeCycleManager {
    
      // Create primary information objects.
      public Organization createOrganization(String name)
       throws JAXRException;
      public Service createService(String name) throws JAXRException;
      public ServiceBinding createServiceBinding() throws JAXRException;
      public Concept createConcept(RegistryObject parent,
                                   InternationalString name,
                                   String value) throws JAXRException;
      public Association createAssociation(RegistryObject targetObject,
                                           Concept associationType)
        throws JAXRException;
    
      // Create demographic information objects.
      public InternationalString createInternationalString(String s)
        throws JAXRException;
      public LocalizedString createLocalizedString(Locale l,String s)
        throws JAXRException;
      public User createUser() throws JAXRException;
      public PersonName createPersonName(String fullName)
       throws JAXRException;
      public EmailAddress createEmailAddress(String address)
       throws JAXRException;
      public TelephoneNumber createTelephoneNumber() throws JAXRException;
      public PostalAddress createPostalAddress(String streetNumber,
                                               String street,
                                               String city,
                                               String stateOrProvince,
                                               String country,
                                               String postalCode,
                                               String type)
       throws JAXRException;
    
      // Creates taxonomy information objects.
      public Classification createClassification(
                                             ClassificationScheme scheme,
                                              String name,String value)
       throws JAXRException;
      public ClassificationScheme createClassificationScheme(
                                                         String name,
                                                         String description)
       throws JAXRException, InvalidRequestException;
      public ExternalIdentifier createExternalIdentifier(
                                ClassificationScheme identificationScheme,
                                String name,String value)
       throws JAXRException;
      public ExternalLink createExternalLink(String externalURI,
                                             String description)
       throws JAXRException;
      public Slot createSlot(String name,String value,String slotType)
       throws JAXRException;
      public SpecificationLink createSpecificationLink()
       throws JAXRException;
    
      // General-purpose create, save, and delete methods.
      public Object createObject(String interfaceName)
       throws JAXRException, InvalidRequestException,
              UnsupportedCapabilityException;
      BulkResponse saveObjects(Collection objects) throws JAXRException;
      BulkResponse deleteObjects(Collection keys) throws JAXRException;
    
      // Get a reference to the Registry Service.
      RegistryService getRegistryService() throws JAXRException;
    }
    Note from the listing, that all the methods defined by the LifeCycleManager are inherited by the BusinessLifeCycleManager interface. Many of the methods are overloaded but we only show one signature for each method. You don't need to study these method definitions too closely; you'll be using most if not all of them in the following sections to create various JAXR information objects. Also the methods have been divided up into methods that create primary information objects, methods that create taxonomy objects, and general-purpose save and delete operations. The getRegistryService() method provides access to the RegistryService that created the LifeCycleManager.

    The BusinessLifeCycleManager

    The BusinessLifeCycleManager is used to add, update, and delete information in the UDDI registry. It represents the UDDI Publishing API. It has about a dozen methods that are used with a UDDI directory. The methods can be grouped into three general categories by their use:
    • To add or update information objects
    • To delete information objects
    • To confirm and undo associations

    The listing below shows the BusinessLifeCycleManager interface

    Java Code: The javax.xml.registry.BusinessLifeCycleManager Interface
    package javax.xml.registry;
    import java.util.*;
    import javax.xml.registry.infomodel.*;
    
    public interface BusinessLifeCycleManager extends LifeCycleManager {
    
       // Add or update information objects in the UDDI registry.
       BulkResponse saveOrganizations(Collection organizations)
         throws JAXRException;
       BulkResponse saveServices(Collection services) throws JAXRException;
       BulkResponse saveServiceBindings(Collection bindings)
        throws JAXRException;
       BulkResponse saveConcepts(Collection concepts) throws JAXRException;
       BulkResponse saveClassificationSchemes(Collection schemes)
         throws JAXRException;
       BulkResponse saveAssociations(Collection associations,
                                     boolean replace)
         throws JAXRException;
    
       // Delete information objects from a UDDI registry.
       BulkResponse deleteOrganizations(Collection organizationKeys)
         throws JAXRException;
       BulkResponse deleteServices(Collection serviceKeys)
         throws JAXRException;
       BulkResponse deleteServiceBindings(Collection bindingKeys)
         throws JAXRException;
       BulkResponse deleteConcepts(Collection conceptKeys)
         throws JAXRException;
       BulkResponse deleteClassificationSchemes(Collection schemeKeys)
         throws JAXRException;
       BulkResponse deleteAssociations(Collection associationKeys)
         throws JAXRException;
    
       // Confirm/undo an association.
       public void confirmAssociation(Association assoc)
         throws JAXRException, InvalidRequestException;
       public void unConfirmAssociation(Association assoc)
         throws JAXRException, InvalidRequestException;
    }
    Note that the saveXXX() methods shown in the above listing are for either adding a new information object to the UDDI registry, or updating an object already in the registry. In the JaxrForNewOrg listing, we used the saveOrganizations() method to add a new Organization to the UDDI registry. Once the Organization object is added to the registry, you need to also save any subsequent changes to it in order to keep the registry synchronized with the JAXR infomodel. For example, changing the name of the Organization instance, requires that you save that information for it to be updated in the UDDI registry. The listing below show you how to update and save an Organization object.

    Java Code: Modify an Organization Object
    InternationalString newName =
      lifeCycleMngr.createInternationalString("ACME Corperation");
    organization.setName( newName );
    
    // Update the UDDI registry.
    Set organizationSet = new HashSet();
    organizationSet.add(myOrganization);
    BulkResponse response = lifeCycleMngr.saveOrganizations(organizationSet);
    Using the BulkResponse Type

    The BusinessLifeCycleManager save and delete methods such as saveOrganizations(), deleteOrganizations(), etc will return the Bulk Response type. The BusinessQueryManager type's findXXX() methods also return the BulkResponse type.

    The BulkResponse

    The purpose of the BulkResponse type is to carry a Collection of arbitrary values whose type is dependent on the method being invoked. For example, the BulkResponse returned by the BusinessQueryManager.findOrganizations() method contains a Collection of Organization objects. However when the BusinessLifeCycleManager.saveOrganizations() method is invoked, the BulkResponse returned contains a Collection of Key objects, one UUID key for each Organization that was saved. The listing below shows the definition of the Bulk Response type:

    Java Code: The javax.xml.registry.BulkResponse Interface
    package javax.xml.registry;
    import java.util.*;
    import javax.xml.registry.infomodel.*;
    
    public interface BulkResponse extends JAXRResponse {
       // Collection of objects returned as a response of a bulk operation.
       public Collection getCollection() throws JAXRException;
    
       // Collection of RegistryException instances for partial commit.
       public Collection getExceptions() throws JAXRException;
    
       // Determines this is a partial response due to large result set.
       public boolean isPartialResponse() throws JAXRException;
    }
    In the listing,the getExceptions() method returns JAXR RegistryException types when the UDDI registry itself encounters an error. The RegistryException types holds codes that correspond to the UDDI SOAP fault message types. These were covered in our article on UDDI, “Tutorial:In Depth Look at UDDI for the Web Service Developer Exam”. There are three RegistryException subtypes:
    • SaveException
    • DeleteException
    • FindException

    These RegistryException subtypes correspond to the kind of method called. For example, the BusinessLifeCycle Manager.saveOrganizations() can return a BulkResponse containing one or more javax.xml.registry.SaveException types. This is the same for the BusinessQuery Manager.findOrganizations() which can return a BulkResponse containing one or more javax.xml.registry.FindException types. If the BusinessQuery Manager.findXXX() method produces a result set that is too large to return in full, and the BulkResponse contains only a portion of the results found by the query, then the isPartialResponse() method will return true. The limit on results returned is determined by the policy set by the UDDI operator.

    You can use the getStatus() method of the BulkResponse which is declared by its supertype JAXRResponse to determine whether the method performed successfully. The possible values for a UDDI registry are:
    • JAXRResponse.STATUS_SUCCESS
    • JAXRResponse.STATUS_FAILURE
    • JAXRResponse.STATUS_WARNING
    • JAXRResponse.STATUS _UNAVAILABLE

    Although the later two values don't apply to UDDI registries. In the listing for JaxrForNewOrg, we processed the BulkResponse in order to determine whether the UDDI registry returned an exception. This is done by calling a doExceptions() method just before the connection is closed. The definition of this method is shown below:

    Java Code: Definition of doExceptions
    public static void doExceptions(BulkResponse rspns) throws JAXRException {
      if(rspns.getStatus()==JAXRResponse.STATUS_SUCCESS){
         System.out.println("\nProgram Complete: No problems reported!");
      }else {
         Iterator exceptions = rspns.getExceptions().iterator();
         while(exceptions.hasNext()){
            Exception je = (Exception)exceptions.next();
            System.out.println("\n***** BulkResponse Exceptions *****\n\n");
            je.printStackTrace();
            System.out.println("\n***********************************");
         }
    }
    The method is used primarily to display a stack trace for exceptions returned by the UDDI registry. If there are no exceptions are returned, then the output will be "Program Complete. No problems reported!" This will tell you that everything executed correctly.

    JAXR Exceptions

    The JAXR API has two mechanisms for returning exceptions. A method can throw them like any other exception, or the exceptions can be returned in a BulkResponse object. The JAXR BusinessLifeCycleManager and BusinessQueryManager objects return multiple results from a method. For example, the saveOrganizations() method returns a Collection of UUID Key objects, one for each Organization saved. A JAXR Inquiry or Publishing method returns multiple results that can include UDDI registry exceptions in a Collection, rather than just throw a single exception. You access these registry exceptions by calling BulkResponse.getExceptions().

    For abnormal conditions such as a NullPointerException, the client-side runtime of the JAXR implementation will throw a JAXRException for the method instead of returning it in the BulkResponse object. Therefore only SOAP faults generated by the UDDI registry are returned as exceptions in a BulkResponse object.

    For methods returning a single value rather than BulkResponse, then all exceptions are thrown directly from the method. The UDDI registry exceptions are of type javax.xml.registry.Registry Exception or one of its subtypes: SaveException, DeleteException, and FindException. The messages returned with these exceptions provide the fault codes and descriptions correlating with the standard UDDI error codes.

    Conclusion

    Although JAXR is not the only API for accessing a UDDI registry, it is the more intuitive and easier to use than other UDDI APIs. Also the JAXR API is flexible enough to accommodate the many of the changes UDDI that will more than likely take place in the coming years. Most importantly though is the fact that JAXR is actually a part of the Java EE 5 platform and for this reason will most like be the key Java UDDI API in the future.
    Last edited by Java Exam; 03-12-2012 at 02:46 PM.

Similar Threads

  1. Replies: 0
    Last Post: 02-17-2012, 01:47 PM
  2. Replies: 0
    Last Post: 02-13-2012, 04:41 PM
  3. Replies: 0
    Last Post: 02-13-2012, 04:33 PM
  4. Replies: 0
    Last Post: 01-19-2012, 01:00 PM
  5. Replies: 0
    Last Post: 12-12-2011, 02:17 PM

Tags for this Thread

Posting Permissions

  • You may not post new threads
  • You may not post replies
  • You may not post attachments
  • You may not edit your posts
  •