Custody  Locate

The Oracle Service Registry demo is used to demonstrate the registry's application programming interface's capabilities and to demonstrate how to use this API.

The Oracle Service Registry Custody demo covers the custody transfer aspects of the UDDI Version 3.01 Specification.. You will learn how to generate a custody transfer token and transfer the ownership of selected structure to another user.

There is a single demo within this package - CustodyDemo. It demonstrates how to generate a transfer token for a selected UDDI key and how to use it to transfer the custody of the structure identified by the UDDI key to another user.

Prerequisites and Preparatory Steps: Code  Locate

We expect that you have already installed the Oracle Service Registry and set the REGISTRY_HOME environment variable to the registry's installation location.

To run the Oracle Service Registry's demos, your registry must be running.

It is necessary to configure the demos. The configuration system has two levels: global and local. The properties defined at the global level may be overwritten at the local level. The global properties are located in the file:

Windows: %REGISTRY_HOME%\demos\env.properties
UNIX: $REGISTRY_HOME/demos/env.properties

The values set during the installation of the Oracle Service Registry work out of the box, and their modification affects all demos. If you need to redefine a property's value for a single demo (that is,, at the local level), edit env.properties. This file is located in the same directory as the file run.sh (run.bat). Local level properties for the Custody demo are loaded from the file:

Windows: %REGISTRY_HOME%\demos\advanced\custody\env.properties
UNIX: $REGISTRY_HOME/demos/advanced/custody/env.properties

Table 8. Properties used in demos

NameDefault ValueDescription
uddi.demos.user.john.namedemo_johnfirst user's name
uddi.demos.user.john.passworddemo_johnfirst user's password
uddi.demos.user.jane.namedemo_janesecond user's name
uddi.demos.user.jane.passworddemo_janesecond user's password
uddi.demos.url.custodyhttp://localhost:8888/registry/uddi/custodythe custody Web service port URL
uddi.demos.url.securityhttp://localhost:8888/registry/uddi/securitythe security Web service port URL

Presentation and Functional Presentation  Locate

This section describes programming pattern of the Custody demo. You can find its source code in the file:

Windows: %REGISTRY_HOME%\demos\advanced\custody\src\demo\uddi\custody\CustodyDemo.java
UNIX: $REGISTRY_HOME/demos/advanced/custody/src/demo/uddi/custody/CustodyDemo.java

To make the demo easier to use, it contains two use cases. The first use case shows the owner of a UDDI structure who wants to transfer it to another user. The second use case is the second user transferring the same structure to his own custody. Let us start with first use case.

We must gather user input first. It is necessary to read user credentials and the key of the structure owned by the user. If you use default values, this means that the user demo_john is transferring custody of the systinet.com:departmentID tModel to user demo_jane. The user logs in and generates a transfer token for the given UDDI key. The transfer token contains information about the registry, expiration time, and secret opaqueToken. Any user who knows these data, can transfer the structure(s) covered by the transferToken.

String user = UserInput.readString("Enter first user name",
	           DemoProperties.getProperty(USER_JOHN_NAME));
String password = UserInput.readString("Enter password",
                   DemoProperties.getProperty(USER_JOHN_PASSWORD));
String uddiKey = UserInput.readString("Enter UDDI key",
                                       "uddi:systinet.com:demo:departmentID");
System.out.println();

UDDI_Security_PortType security = getSecurityStub();
String authInfo = getAuthInfo(user, password, security);
Get_transferToken get = createGetTransferToken(uddiKey, authInfo);
TransferToken token = getTransferToken(get);
printTransferToken(token);
discardAuthInfo(authInfo, security);

The helper method getCustodyStub() returns the UDDI Custody stub of the Web service listening at the URL specified by the URL_CUSTODY property.

public static UDDI_CustodyTransfer_PortType getCustodyStub() throws SOAPException {
    // you can specify your own URL in property - uddi.demos.url.custody
    String url = DemoProperties.getProperty(URL_CUSTODY, "http://localhost:8888/registry/uddi/custody");
    System.out.print("Using Custody at url " + url + " ..");
    UDDI_CustodyTransfer_PortType custody = UDDICustodyStub.getInstance(url);
    System.out.println(" done");
    return custody;
}

The createGetTransferToken() method is used to create the Get_transferToken object, which encapsulates the parameters of this UDDI call. In this example we set authInfo and a single key for the UDDI structure to be transferred int the custody of the second user.

public static Get_transferToken createGetTransferToken(String uddiKey, String authInfo)
  throws InvalidParameterException {
    System.out.println("uddiKey = " + uddiKey);
    Get_transferToken get = new Get_transferToken();
    get.addKey(uddiKey);
    get.setAuthInfo(authInfo);
    return get;
}

The next step is to invoke the get_transferToken UDDI call and get the result, which is a TransferToken.

public static TransferToken getTransferToken(Get_transferToken get)
  throws UDDIException, SOAPException {
    UDDI_CustodyTransfer_PortType custody = getCustodyStub();
    System.out.print("Get in progress ...");
    TransferToken token = custody.get_transferToken(get);
    System.out.println(" done");
    return token;
}

At this point the first user, John Demo, has generated a transfer token. He can discard it or send it to the second user Jane Demo, so she can transfer the entities to her custody. The transfer token must be kept secret, so plain text transports such as unencrypted emails are not suitable for this purpose. Let us suppose that Jane Demo has received the transfer token already. She logs in, creates a Transfer_entities object and invokes the UDDI call transfer_entities.

user = UserInput.readString("Enter second user name",
	                                DemoProperties.getProperty(USER_JANE_NAME));
password = UserInput.readString("Enter password", DemoProperties.getProperty(USER_JANE_PASSWORD));
System.out.println();

authInfo = getAuthInfo(user, password, security);
Transfer_entities transfer = createTransferEntities(uddiKey, token, authInfo);
transferEntities(transfer);
discardAuthInfo(authInfo, security);

The createTransferEntities() method is used to create Transfer_entities object, which encapsulates parameters of same name UDDI call. In this example we set Jane's authInfo, UDDI key to be transferred, and the TransferToken generated by John.

public static Transfer_entities createTransferEntities(String uddiKey,
	                                                          TransferToken token, String authInfo)
  throws InvalidParameterException {
    Transfer_entities transfer = new Transfer_entities();
    transfer.addKey(uddiKey);
    transfer.setTransferToken(token);
    transfer.setAuthInfo(authInfo);
    return transfer;
}

The final step is to make the transfer_entities UDDI call. When it successfully returns, the second user (Jane) is the happy owner of the UDDI structure systinet.com:demo:departmentID.

public static void transferEntities(Transfer_entities transfer)
  throws UDDIException, SOAPException {
    UDDI_CustodyTransfer_PortType custody = getCustodyStub();
    System.out.print("Transfer in progress ...");
    custody.transfer_entities(transfer);
    System.out.println(" done");
}

Building and Running Demos  Locate

This section shows how to build and run the Oracle Service Registry Custody demo.

  1. Be sure that the demos are properly configured and the Oracle Service Registry is up and running.

  2. Change your working directory to

    Windows: %REGISTRY_HOME%\demos\advanced\custody
    UNIX: $REGISTRY_HOME/demos/advanced/custody

  3. Build demo using:

    Windows: run.bat make
    UNIX: ./run.sh make

    [Note]Note

    When compiling demos on Windows platforms, you may see the following text:

    A subdirectory or file ..\..\common\.\build\classes already exists.

    This is expected and does not indicate a problem.

  4. To get list of all available commands, run

    Windows: run.bat help
    UNIX: ./run.sh help

  5. The demo can be executed via the run command, using the name of the demo as a parameter. To run the Custody demo, invoke

    Windows: run.bat CustodyDemo
    UNIX: ./run.sh CustodyDemo

    The output of this demo will resemble the following:

    Running CustodyDemo demo...
    
    Getting transfer token where
    Enter first user name [demo_john]:
    Enter password [demo_john]:
    Enter UDDI key [uddi:systinet.org:demo:departmentID]:
    
    Using Security at url https://mycomp.com:8443/registry/uddi/security .. done
    Logging in .. done
    uddiKey = uddi:systinet.org:demo:departmentID
    Using Custody at url https://mycomp.com:8443/registry/uddi/custody .. done
    Get in progress ... done
    
    TransferToken
    <transferToken xmlns="urn:uddi-org:custody_v3">
    <nodeID xmlns="urn:uddi-org:api_v3">Systinet</nodeID>
    <expirationTime>2004-05-17T12:32:51.236+02:00</expirationTime>
    <opaqueToken>ZmZmZmZmZmZlMDVmZGEzNg==</opaqueToken>
    </transferToken>
    
    Logging out .. done
    
    Transfering custody where
    Enter second user name [demo_jane]:
    Enter password [demo_jane]:
    
    Logging in .. done
    Using Custody at url https://mycomp.com:8443/registry/uddi/custody .. done
    Transfer in progress ... done
    Logging out .. done
  6. To rebuild demos, execute run.bat clean (./run.sh clean) to delete the classes directory and run.bat make (./run.sh make) to rebuild the demo classes.