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

• Organizing Objects Within Registry Packages

• Changing the State of Objects in the Registry

• Controlling Access to Objects

• Removing Objects From the Registry and Repository

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:

• AccessControlPolicyFor

• AffiliatedWith, which has the subconcepts EmployeeOf and MemberOf

• Contains

• ContentManagementServiceFor

• EquivalentTo

• Extends

• ExternallyLinks

• HasFederationMember

• HasMember

• Implements

• InstanceOf

• InvocationControlFileFor, which has the subconcepts CatalogingControlFileFor and ValidationControlFileFor

• OffersService

• OwnerOf

• RelatedTo

• Replaces

• ResponsibleFor

• SubmitterOf

• 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 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.

To 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.

   The output of the run target looks something like this:

   run: [java] ID 1 is urn:uuid:176d2620-7733-4d74-9525-854dd4d2dbe0 [java] ID 2 is urn:uuid:0302e35b-c104-41c7-85f1-96f51f9ac56b [java] Query URL is http://localhost:6480/soar/registry/soap [java] Publish URL is http://localhost:6480/soar/registry/soap [java] Created connection to registry [java] Established security credentials [java] Got registry service, query manager, and life cycle manager [java] Object type is Organization [java] Object name is Child Organization 1 [java] Object description is child organization 1 [java] Child Organization 1 created 2007-07-22 23:30:15.0 [java] Object type is Organization [java] Object name is Child Organization 2 [java] Object description is child organization 2 [java] Child Organization 2 created 2007-07-22 23:30:15.0 [java] Concept value: RelatedTo [java] Classification scheme is AssociationType [java] Association ID is urn:uuid:36f72e8f-bc87-47ea-8e22-a199b1be0276 [java] Association saved

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 Command in Service Registry 3.1 Update 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.

To 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

   The output of the pub-pkg target looks something like this:

   pub-pkg: [java] Query URL is http://localhost:6480/soar/registry/soap [java] Publish URL is http://localhost:6480/soar/registry/soap [java] Created connection to registry [java] Established security credentials [java] Got registry service and life cycle manager [java] Package ID is urn:uuid:182e383b-1244-4e9f-9439-bddac093ebe7 [java] Object type is ClassificationNode [java] Object name: Household Refrigerator and Home Freezer Manufacturing [java] Object type is ClassificationNode [java] Object name: Freestanding Ambulatory Surgical and Emergency Centers [java] Object type is Federation [java] Object name: freebXMLRegistryFederation [java] Object type is Organization [java] Object name: freebXMLRegistry [java] Object type is Registry [java] Object name: freebXMLRegistry [java] Package saved

3. Type the following command:

   Ant-base/ant search-pkg

   The output of the search-pkg target looks something like this:

   search-pkg: [java] Query URL is http://localhost:6480/soar/registry/soap [java] Created connection to registry [java] Got registry service and query manager [java] Contents of FreePackage: [java] Object type is Registry [java] Object name: freebXMLRegistry [java] Object description: freebXML Registry [java] Object key id: urn:uuid:48b099a8-ed72-454e-9075-a6f96bd1280a [java] Object type is Federation [java] Object name: freebXMLRegistryFederation [java] Object description: freebXML Registry Federation [java] Object key id: urn:uuid:51f410c3-de34-47f6-845d-eeda495c458a [java] Object type is ClassificationNode [java] Object name: Household Refrigerator and Home Freezer Manufacturing [java] Object description: null [java] Object key id: urn:uuid:4f368d2d-25a4-413f-8609-a91166f1333f [java] Object type is ClassificationNode [java] Object name: Freestanding Ambulatory Surgical and Emergency Centers [java] Object description: null [java] Object key id: urn:uuid:ad381518-6986-444d-95ba-e62d85e2e84a [java] Object type is Organization [java] Object name: freebXMLRegistry [java] Object description: freebXML Registry [java] Object key id: urn:freebxml:registry:Organization:freebXMLRegistry

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:

• Saving an object to the Registry creates an EVENT_TYPE_CREATED event.

• The following actions create an EVENT_TYPE_VERSIONED event if versioning is enabled for the object type of the object being modified:

  • Changing an object’s name or description

  • Adding, modifying, or removing a Classification, ExternalIdentifier, or Slot

  • 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 for details.

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 in Service Registry in Service Registry 3.1 Update 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.

• You can approve objects by using the LifeCycleManagerImpl.approveObjects method. This feature is implementation-specific.

• You can deprecate objects by using the LifeCycleManager.deprecateObjects method.

• You can undeprecate objects by using the LifeCycleManager.unDeprecateObjects method.

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.

To 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

   For example, if you specify the unique identifier of the RegistryPackage object you created in Organizing Objects Within Registry Packages: Examples, the output of the approve-obj target looks something like this:

   approve-obj: [java] ID string is urn:uuid:182e383b-1244-4e9f-9439-bddac093ebe7 [java] Query URL is http://localhost:6480/soar/registry/soap [java] Publish URL is http://localhost:6480/soar/registry/soap [java] Created connection to registry [java] Established security credentials [java] Got registry service, query manager, and life cycle manager [java] Object type is RegistryPackage [java] Object name is FreePackage [java] Object description is Package with objects named free [java] Object key id is urn:uuid:182e383b-1244-4e9f-9439-bddac093ebe7 [java] Current audit trail: [java] FreePackage created 2007-07-23 01:21:40.0 [java] Approved the object [java] Object saved [java] Audit trail for approved object: [java] FreePackage created 2007-07-23 01:21:40.0 [java] FreePackage approved 2007-07-23 01:28:26.0

3. Type the following command:

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

   The output of the deprecate-obj target for the same object looks something like this:

   deprecate-obj: [java] ID string is urn:uuid:182e383b-1244-4e9f-9439-bddac093ebe7 [java] Query URL is http://localhost:6480/soar/registry/soap [java] Publish URL is http://localhost:6480/soar/registry/soap [java] Created connection to registry [java] Established security credentials [java] Got registry service, query manager, and life cycle manager [java] Object type is RegistryPackage [java] Object name is FreePackage [java] Object description is Package with objects named free [java] Object key id is urn:uuid:182e383b-1244-4e9f-9439-bddac093ebe7 [java] Current audit trail: [java] FreePackage created 2007-07-23 01:21:40.0 [java] FreePackage approved 2007-07-23 01:28:26.0 [java] Deprecated the object [java] Object saved [java] Audit trail for deprecated object: [java] FreePackage created 2007-07-23 01:21:40.0 [java] FreePackage approved 2007-07-23 01:28:26.0 [java] FreePackage deprecated 2007-07-23 01:30:47.0

4. Type the following command:

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

   The output of the undeprecate-obj target for the same object looks something like this:

   undeprecate-obj: [java] ID string is urn:uuid:182e383b-1244-4e9f-9439-bddac093ebe7 [java] Query URL is http://localhost:6480/soar/registry/soap [java] Publish URL is http://localhost:6480/soar/registry/soap [java] Created connection to registry [java] Established security credentials [java] Got registry service, query manager, and life cycle manager [java] Object type is RegistryPackage [java] Object name is FreePackage [java] Object description is Package with objects named free [java] Object key id is urn:uuid:182e383b-1244-4e9f-9439-bddac093ebe7 [java] Current audit trail: [java] FreePackage created 2007-07-23 01:21:40.0 [java] FreePackage approved 2007-07-23 01:28:26.0 [java] FreePackage deprecated 2007-07-23 01:30:47.0 [java] Undeprecated the object [java] Object saved [java] Audit trail for undeprecated object: [java] FreePackage created 2007-07-23 01:21:40.0 [java] FreePackage approved 2007-07-23 01:28:26.0 [java] FreePackage deprecated 2007-07-23 01:30:47.0 [java] FreePackage undeprecated 2007-07-23 01:32:05.0

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:

• The predefined user Registry Guest can read any object. All users have this identity when they are not logged in to the Registry.

• All registered users can create objects and can perform actions on objects they own.

• Any user classified as a RegistryAdministrator can perform actions on all objects in the Registry. By default, only the predefined user Registry Operator is classified as an administrator. For instructions on how to become an administrator, see Creating an Administrator for Service Registry in Service Registry 3.1 Update 1 Administration Guide.

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.

To 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

   The output of the run target looks something like this:

   run: [java] URN is urn:uuid:182e383b-1244-4e9f-9439-bddac093ebe7 [java] Query URL is http://localhost:6480/soar/registry/soap [java] Publish URL is http://localhost:6480/soar/registry/soap [java] Created connection to registry [java] Established security credentials [java] Got registry service and life cycle manager [java] Deleting object with id urn:uuid:182e383b-1244-4e9f-9439-bddac093ebe7 [java] Object deleted [java] Object URN was urn:uuid:182e383b-1244-4e9f-9439-bddac093ebe7