test

Service Registry 3.1 Developer's Guide

Chapter 5 Managing Objects in the Registry

After you publish objects to Service Registry, you can perform operations on the objects. This chapter describes these operations.

Creating Relationships Between Objects: Associations

You can create an Association object and use it to specify a relationship between any two objects. The ebXML specification specifies an AssociationType 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.

The canonical association types are as follows:

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 Service as the target.

    Associations are directional: each Association object has a source object and a target object. Establishing an association between two objects is a three-step process:

  1. Find the AssociationType concept that you want to use, or create one.

  2. Use the LifeCycleManager.createAssociation method to create the association. 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.

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 RelatedTo concept:


// Find RelatedTo concept for Association
String concString = 
    CanonicalConstants.CANONICAL_ASSOCIATION_TYPE_ID_RelatedTo;
Concept relConcept = (Concept) bqm.getRegistryObject(concString);

Create the association, specifying obj2 as the target:


Association relAssoc =
     blcm.createAssociation(obj2, relConcept);

Add the association to the source object, obj1:


obj1.addAssociation(relAssoc);

Finally, save the association:


Collection associations = new ArrayList();
associations.add(relAssoc1);
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 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 JAXRPublishAssociation.java in the directory INSTALL/registry-samples/publish-association/src/. This example creates a RelatedTo association between any two objects whose unique identifiers you specify. For example, you could specify the two child organizations created in Creating and Retrieving an Organization Hierarchy: Examples.

ProcedureTo Run the JAXRPublishAssociation Example

  1. Go to the directory INSTALL/registry-samples/organizations.

  2. Retrieve the organization hierarchy by running the following command:


    Ant-base/ant search-fam

    Notice the key ID strings of the two child organizations.

  3. Go to the directory INSTALL/registry-samples/publish-association.

  4. Type the following command:


    Ant-base/ant run -Did1=string1 -Did2=string2

    Replace string1 and string2 with the two child organization ID strings.

    Whether the association is intramural or extramural depends upon who owns the two objects. In this case, the association is intramural.

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. A RegistryPackage is analogous to a directory or folder in a file system, and the registry objects it contains are analogous to the files in the directories or folders.

To create a RegistryPackage object, call the LifeCycleManager.createRegistryPackage method, which takes a String or InternationalString argument. Then call the RegistryPackage.addRegistryObject or RegistryPackage.addRegistryObjects method to add objects to the package.

For example, you could create a RegistryPackage object that is named “SunPackage”:

RegistryPackage pkg =
     blcm.createRegistryPackage("SunPackage");

Then, 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 use the cp command of the Admin Tool to load a file system into the Registry, storing the directories as registry packages and the files as the package contents. See cp in Service Registry 3.1 Administration Guide for details.

Organizing Objects Within Registry Packages: Examples

For examples of using registry packages, see JAXRPublishPackage.java and JAXRSearchPackage.java in the directory INSTALL/registry-samples/packages/src. 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.

ProcedureTo Run the JAXRPublishPackage and JAXRSearchPackage Examples

  1. Go to the directory INSTALL/registry-samples/packages.

  2. Type the following command:


    Ant-base/ant pub-pkg

  3. Type the following command:


    Ant-base/ant search-pkg

Changing the State of Objects in the Registry

You add an AuditableEvent object to the audit trail of an object when you publish the object to the Registry or when you modify the object in certain ways. See Retrieving the Audit Trail of an Object for details on these events and on how to obtain information about them.

Many events are created as a side effect of some other action:

Note –

At this release, versioning of objects is disabled by default. To enable versioning of objects, an administrator must perform the task described in Enabling Versioning of Registry Objects in Service Registry 3.1 Administration Guide. The administrator commonly enables versioning for some object types but not for all.

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 where 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. If you change your mind after deprecating an object, you can undeprecate it. As a registered user, you can perform these actions only on objects you own.

The LifeCycleManagerImpl.approveObjects method has the following signature:

public BulkResponse approveObjects(java.util.Collection keys)
    throws JAXRException

The code to deprecate an object typically looks like this:

String id = id-string;
Key key = blcm.createKey(id);
Collection keys = new ArrayList();
keys.add(key);

// deprecate the object
blcm.deprecateObjects(keys);

It is possible to restrict access to these actions to specific users, user roles, and user groups, such as registry administrators. See Controlling Access to Objects.

No AuditableEvent is created for actions that do not alter the state of a RegistryObject. For example, queries do not generate an AuditableEvent, and no AuditableEvent is generated for a RegistryObject when it is added to a RegistryPackage 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 examples in INSTALL/registry-samples/auditable-events/src: JAXRApproveObject.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.

For all examples, the object that you specify must be one that you created.

ProcedureTo Run the JAXRApproveObject, JAXRDeprecateObject, and JAXRUndeprecateObject Examples

  1. Go to the directory INSTALL/registry-samples/auditable-events.

  2. Type the following command:


    Ant-base/ant approve-obj -Did=id-string

  3. Type the following command:


    Ant-base/ant deprecate-obj -Did=id-string

  4. Type the following command:


    Ant-base/ant undeprecate-obj -Did=id-string

Controlling Access to Objects

Access to objects in the Registry is set by access control policies (ACPs). The default access control policy specifies the following:

Very fine-grained access control on individual objects is possible through custom ACPs. However, writing an ACP is currently a manual process that requires knowledge of OASIS eXtensible Access Control Markup Language (XACML). For details, refer to Chapter 9, “Access Control Information Model,” of ebXML RIM 3.0, especially the examples in Sections 9.7.6 through 9.7.8.

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.deleteObjects method.

The following code fragment deletes the object that corresponds to a specified key string and then displays the key again so that you can confirm that it has deleted the correct one.

String id = key.getId();
Collection keys = new ArrayList();
keys.add(key);
BulkResponse response = blcm.deleteObjects(keys);
Collection exceptions = response.getException();
if (exceptions == null) {
    System.out.println("Objects deleted");
    Collection retKeys = response.getCollection();
    Iterator keyIter = retKeys.iterator();
    javax.xml.registry.infomodel.Key orgKey = null;
    if (keyIter.hasNext()) {
        orgKey =
             (javax.xml.registry.infomodel.Key) keyIter.next();
        id = orgKey.getId();
        System.out.println("Object key was " + id);
    }
}

Deleting an Organization object does not delete the Service and User objects that belong to the Organization. If you want to delete those objects, you must delete them separately.

Deleting a Service object deletes the ServiceBinding objects that belong to it. Deleting the Service and ServiceBinding objects, however, does not delete the associated ExtrinsicObject instances and their associated repository items. You must delete the extrinsic objects separately.

When you delete an object that has Classification or ExternalIdentifier or Slot objects, those objects are also deleted. However, if the object has ExternalLink objects, those objects are not deleted.

AuditableEvent objects are not deleted when the objects associated with them are deleted. You might find that as you use the Registry, a large number of these objects accumulates.

Removing Objects from the Registry: Example

For an example of deleting an object from the Registry, see JAXRDelete.java in the directory INSTALL/registry-samples/delete-object/src. This example deletes the object whose unique identifier you specify.

ProcedureTo Run the JAXRDelete Example

  1. Go to the directory INSTALL/registry-samples/delete-object.

  2. Type the following command:


    Ant-base/ant run -Did=id-string