Retrieving Information About an Object

After 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:

• Name

• Description

• Type

• Unique identifier and logical identifier

• Classifications

• External identifiers

• External links

• Slots

For an organization, you can also retrieve the following:

• The primary contact, which is a User object

• Postal address

• Telephone numbers

• Services

For a service, you can retrieve the service bindings.

For any 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:

• Retrieving the Identifier Values for an Object

• Retrieving the Name or Description of an Object

• Retrieving the Type of an Object

• Retrieving the Classifications for an Object

• Retrieving the External Identifiers for an Object

• Retrieving the External Links for an Object

• Retrieving the Slots for an Object

• Retrieving the Attributes of an Organization or User

• Retrieving the Services and Service Bindings for an Organization

• Retrieving an Organization Hierarchy

• Retrieving the Audit Trail of an Object

• Retrieving the Version of an Object

Retrieving the Identifier Values for an Object

The unique identifier for an object is contained in a Key object. A Key is a structure that contains the identifier in the form of an id attribute that is a String value. To retrieve the identifier, call the method RegistryObject.getKey().getId().

The JAXR provider also has an implementation-specific method for retrieving the logical identifier, which is called a lid. The lid is a String attribute of a RegistryObject. To retrieve the lid, call RegistryObjectImpl.getLid. The method has the following signature:

public java.lang.String getLid()
    throws JAXRException

For an example of the use of this method, see JAXRSearchOrg.java in the directory <INSTALL>/registry/samples/organizations/src. For more information on this example, see Retrieving Organization Attributes: Example.

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.getDescription return the LocalizedString object for the default locale. You can then retrieve the String value of the LocalizedString object. The following code fragment uses these methods:

String name = ro.getName().getValue();
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, JAXRGetMyObjects.java in the directory <INSTALL>/registry/samples/get-objects/src.

Retrieving the Type of an Object

If you have searched the Registry without specifying a particular object type, you can retrieve the type of the objects returned by the search. Use the RegistryObject.getObjectType method, which returns a Concept value. You can then use the Concept.getValue method to obtain the String value of the object type. The following code fragment uses these methods:

Concept objType = object.getObjectType();
System.out.println("Object type is " + objType.getValue());

The concept will be one of those in the canonical classification scheme ObjectType. For an example of this code, see JAXRSearchByName.java in the directory <INSTALL>/registry/samples/search-name/src.

Retrieving the Classifications for an Object

Use the RegistryObject.getClassifications method to retrieve a Collection of the object’s classifications. For a classification, the important attributes are its value and the classification scheme to which it belongs. Often, a classification has no name or description. The following code fragment retrieves and displays an object’s classifications.

Collection classifications = object.getClassifications();
Iterator classIter = classifications.iterator();
while (classIter.hasNext()) {
    Classification classification =
         (Classification) classIter.next();
    String name = classification.getName().getValue();
    System.out.println("  Classification name is " + name);
    System.out.println("  Classification value is " +
        classification.getValue());
    ClassificationScheme scheme =
         classification.getClassificationScheme();
    System.out.println("  Classification scheme for " +
        name + " is " + scheme.getName().getValue());
}

Some of the examples have a showClassifications method that uses code similar to this. See, for example, JAXRSearchByName.java in the directory <INSTALL>/registry/samples/search-name/src.

Retrieving the External Identifiers for an Object

Use the RegistryObject.getExternalIdentifiers method to retrieve a Collection 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 external identifier, the method that retrieves the classification scheme is getIdentificationScheme. The following code fragment retrieves and displays an object’s external identifiers.

Collection exIds = object.getExternalIdentifiers();
Iterator exIdIter = exIds.iterator();
while (exIdIter.hasNext()) {
    ExternalIdentifier exId =
         (ExternalIdentifier) exIdIter.next();
    String name = exId.getName().getValue();
    System.out.println("  External identifier name is " +
        name);
    String exIdValue = exId.getValue();
    System.out.println("  External identifier value is " +
         exIdValue);
    ClassificationScheme scheme =
         exId.getIdentificationScheme();
    System.out.println("  External identifier " +
         "classification scheme is " +
         scheme.getName().getValue());
}

Some of the examples have a showExternalIdentifiers method that uses code similar to this. See, for example, JAXRSearchByName.java in the directory <INSTALL>/registry/samples/search-name/src.

Retrieving the External Links for an 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.iterator();
while (exLinkIter.hasNext()) {
    ExternalLink exLink = (ExternalLink) exLinkIter.next();
    String name = exLink.getName().getValue();
    if (name != null) {
        System.out.println("  External link name is " + name);
    }
    String description = exLink.getDescription().getValue();
    System.out.println("  External link description is " +
        description);
    String externalURI = exLink.getExternalURI();
    System.out.println("  External link URI is " +
         externalURI);
}

Some of the examples have a showExternalLinks method that uses code similar to this. See, for example, JAXRSearchByName.java in the directory <INSTALL>/registry/samples/search-name/src.

Retrieving the Slots for an Object

Slots are arbitrary attributes that you can create for an object. Use the RegistryObject.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 values. The following fragment retrieves and displays an object’s slots:

Collection slots = object.getSlots();
Iterator slotIter = slots.iterator();
while (slotIter.hasNext()) {
    Slot slot = (Slot) slotIter.next();
    String name = slot.getName();
    System.out.println("  Slot name is " + name);
    Collection values = slot.getValues();
    Iterator valIter = values.iterator();
    int count = 1;
    while (valIter.hasNext()) {
        String value = (String) valIter.next();
        System.out.println("  Slot value " + count++ +
             ": " + value);
    }
    String type = slot.getSlotType();
    if (type != null) {
        System.out.println("  Slot type is " + type);
}

Some of the examples have a showSlots method that uses this code. See, for example, JAXRSearchByName.java in the directory <INSTALL>/registry/samples/search-name/src.

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 that are available to all other objects. Every organization also has a User object as a primary contact. The organization can have additional affiliated User objects.

The attributes for a User object include a PersonName object, which has a different 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.

To retrieve the postal address for an organization, call the Organization.getPostalAddress method as follows (org is the organization):

PostalAddress pAd = org.getPostalAddress();

After you retrieve the address, you can retrieve the address attributes as follows:

System.out.println(" Postal Address:\n  " +
    pAd.getStreetNumber() + " " + pAd.getStreet() +
    "\n  " + pAd.getCity() + ", " +
    pAd.getStateOrProvince() + " " +
    pAd.getPostalCode() + "\n  " + pAd.getCountry() +
    "(" + pAd.getType() + ")");

To retrieve the primary contact for an organization, call the Organization.getPrimaryContact method as follows (org is the organization):

User pc = org.getPrimaryContact();

To retrieve the postal addresses for a user, call the User.getPostalAddresses method and extract the Collection values as follows (pc is the primary contact):

Collection pcpAddrs = pc.getPostalAddresses();
Iterator pcaddIter = pcpAddrs.iterator();
while (pcaddIter.hasNext()) {
    PostalAddress pAd = (PostalAddress) pcaddIter.next();
    /* 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 organization. The code retrieves the country code, area code, main number, and type of the telephone number.

Collection orgphNums = org.getTelephoneNumbers(null);
Iterator orgphIter = orgphNums.iterator();
while (orgphIter.hasNext()) {
    TelephoneNumber num = (TelephoneNumber) orgphIter.next();
    System.out.println(" Phone number: " +
         "+" + num.getCountryCode() + " " +
        "(" + num.getAreaCode() + ") " +
        num.getNumber() + " (" + num.getType() + ")");
}

A TelephoneNumber can also have an extension, retrievable through the getExtension method. If the number can be dialed electronically, it can have a url attribute, retrievable through the getUrl method.

To retrieve the name of a user, call the User.getPersonName method. A PersonName 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.println(" Contact name: " +
    pcName.getFirstName() + " " +
    pcName.getMiddleName() + " " +
    pcName.getLastName());

To retrieve the email addresses for a user, call the User.getEmailAddresses method. An EmailAddress has two attributes, the address and its type. In the following code fragment, pc is the primary contact.

Collection eAddrs = pc.getEmailAddresses();
Iterator eaIter = eAddrs.iterator();
while (eaIter.hasNext()) {
    EmailAddress eAd = (EmailAddress) eaIter.next();
    System.out.println("  Email address: " +
        eAd.getAddress() + " (" + eAd.getType() + ")");
}

The attributes for PostalAddress, TelephoneNumber, PersonName, and EmailAddress objects are all String values. As noted in JAXR Information Model Interfaces, 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 JAXRSearchOrg.java in the directory <INSTALL>/registry/samples/organizations/src, which displays information about an organization whose name contains a specified string.

To Run the JAXRSearchOrg Example

Steps

1. Go to the directory <INSTALL>/registry/samples/organizations.

2. Type the following command:

   asant search-org -Dorg=string

Retrieving the Services and Service Bindings for an Organization

Most 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. The specification link provides the linkage between a service binding and a technical specification that describes how to use the service through the service binding. A specification link has the following attributes:

• A specification object, which is typically an ExtrinsicObject

• A usage description, which is an InternationalString object

• A Collection of usage parameters, which are String values

You can use the Service.getProvidingOrganization method to retrieve the organization that provides a service, and you can use the ServiceBinding.getService method to retrieve the service for a service binding.

The following code fragment retrieves the services for the organization org. Then it retrieves the service bindings for each service and, for each service binding, its access URI and specification links.

Collection services = org.getServices();
Iterator svcIter = services.iterator();
while (svcIter.hasNext()) {
    Service svc = (Service) svcIter.next();
    System.out.println(" Service name: " + getName(svc));
    System.out.println(" Service description: " +
        getDescription(svc));

    Collection serviceBindings = svc.getServiceBindings();
    Iterator sbIter = serviceBindings.iterator();
    while (sbIter.hasNext()) {
        ServiceBinding sb = (ServiceBinding) sbIter.next();
        System.out.println("  Binding name: " +
            getName(sb));
        System.out.println("  Binding description: " +
            getDescription(sb));
        System.out.println("  Access URI: " +
            sb.getAccessURI());

        Collection specLinks = sb.getSpecificationLinks();
        Iterator slIter = specLinks.iterator();
        while (slIter.hasNext()) {
            SpecificationLink sl =
                 (SpecificationLink) slIter.next();
            RegistryObject ro = sl.getSpecificationObject();
            System.out.println("Specification link " +
                "object of type " + ro.getObjectType());
            System.out.println("Usage description: " +
                sl.getUsageDescription().getValue());
            Collection ups = sl.getUsageParameters();
            Iterator upIter = ups.iterator();
            while (upIter.hasNext()) {
                String up = (String) upIter.next();
                System.out.println("Usage parameter: " +
                     up);
             }
        }
    }
}

The example Retrieving Organization Attributes: Example also displays the services and service bindings for the organizations it finds.

Services often exist independent of an organization. You can search for services directly using the BusinessQueryManagerImpl.findObjects method.

Retrieving an Organization Hierarchy

JAXR allows you to group organizations into families. One organization can have other organizations as its children. The child organizations can also have children. Therefore, any given organization can have a parent, children, and descendants.

The Organization.getParentOrganization method retrieves an organization’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 organization.

Collection children = org.getChildOrganizations();

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 Retrieving an Organization Hierarchy: Examples.

Retrieving the Audit Trail of an Object

Whenever an object is published to the Registry, and whenever it is modified in any way, the JAXR provider creates another object, called an AuditableEvent. The JAXR provider adds the AuditableEvent object 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 RegistryObject.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 Retrieving the Audit Trail of an Object.

Table 3–4 AuditableEvent Types

Event Type	Description
EVENT_TYPE_CREATED	Object was created and was published to the registry.
EVENT_TYPE_DELETED	Object was deleted using one of the LifeCycleManager or BusinessLifeCycleManager deletion methods.
EVENT_TYPE_DEPRECATED	Object was deprecated using the LifeCycleManager.deprecateObjects method.
EVENT_TYPE_UNDEPRECATED	Object was undeprecated using the LifeCycleManager.unDeprecateObjects method.
EVENT_TYPE_VERSIONED	A new version of the object was created. This event typically happens when any of the object’s attributes changes.
EVENT_TYPE_UPDATED	Object was updated.
EVENT_TYPE_APPROVED	Object was approved using the LifeCycleManagerImpl.approveObjects method (implementation-specific).
EVENT_TYPE_DOWNLOADED	Object was downloaded (implementation-specific).
EVENT_TYPE_RELOCATED	Object was relocated (implementation-specific).

The following code fragment retrieves the audit trail for a registry object, displaying the type and timestamp of each event:

Collection events = obj.getAuditTrail();
String objName = obj.getName().getValue();
Iterator eventIter = events.iterator();
while (eventIter.hasNext()) {
    AuditableEventImpl ae = (AuditableEventImpl) eventIter.next();
    int eType = ae.getEventType();
    if (eType == AuditableEvent.EVENT_TYPE_CREATED) {
        System.out.print(objName + " created ");
    } else if (eType == AuditableEvent.EVENT_TYPE_DELETED) {
        System.out.print(objName + " deleted ");
    } else if (eType == AuditableEvent.EVENT_TYPE_DEPRECATED) {
        System.out.print(objName + " deprecated ");
    } else if (eType == AuditableEvent.EVENT_TYPE_UNDEPRECATED) {
        System.out.print(objName + " undeprecated ");
    } else if (eType == AuditableEvent.EVENT_TYPE_UPDATED) {
        System.out.print(objName + " updated ");
    } else if (eType == AuditableEvent.EVENT_TYPE_VERSIONED) {
        System.out.print(objName + " versioned ");
    } else if (eType == AuditableEventImpl.EVENT_TYPE_APPROVED) {
        System.out.print(objName + " approved ");
    } else if (eType == AuditableEventImpl.EVENT_TYPE_DOWNLOADED) {
        System.out.print(objName + " downloaded ");
    } else if (eType == AuditableEventImpl.EVENT_TYPE_RELOCATED) {
        System.out.print(objName + " relocated ");
    } else {
        System.out.print("Unknown event for " + objName + " ");
    }System.out.println(ae.getTimestamp().toString());
}

Some of the examples have a showAuditTrail method that uses code similar to this. See, for example, JAXRSearchByName.java in the directory <INSTALL>/registry/samples/search-name/src.

See Changing the State of Objects in the Registry 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 version of the object. For details on how versioning happens, see Changing the State of Objects in the Registry. When you first create an object, the object has a version of 1.1.

To retrieve the version of an object, use the implementation-specific getVersionInfo method for a registry object, which returns a VersionInfoType object. The method has the following signature:

public VersionInfoType getVersionInfo()
    throws JAXRException

For example, to retrieve the version number for the organization org, cast org to a RegistryObjectImpl when you call the method. Then call the VersionInfoType.getVersionName method, which returns a String.

import org.oasis.ebxml.registry.bindings.rim.VersionInfoType;
...
VersionInfoType vInfo =
     ((RegistryObjectImpl)org).getVersionInfo();
if (vInfo != null) {
    System.out.println("Org version: " +
        vInfo.getVersionName());
}

Some of the examples use code similar to this. See, for example, JAXRSearchByName.java in the directory <INSTALL>/registry/samples/search-name/src.