Managing Objects in the Registry

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, if none of the canonical ones are suitable.

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 has a source object and a target object. Establishing an association between two objects is a three-step process:

  1. Find the AssociationType concept you wish 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 concept named RelatedTo: 

// Find RelatedTo concept for Association
Collection namePatterns = new ArrayList();
namePatterns.add("RelatedTo");
BulkResponse br = bqm.findObjects("Concept", null, 
  namePatterns, null, null, null, null);
Collection concepts = br.getCollection();

Iterate through the concepts (there should only be one) to find the right one. 

Concept relConcept = (Concept) concIter.next();

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 <INSTALL>/registry/samples/publish-association/src/JAXRPublishAssociation.java. This example creates a RelatedTo association between any two objects whose unique identifiers you specify. For example, you could specify the identifiers of the two child organizations created in Creating and Retrieving an Organization Hierarchy: Example. To run the example, follow these steps:

  1. Go to the directory <INSTALL>/registry/samples/publish-association.
  2. Type the following command:

    3. ant run -Did1=string1 -Did2=string2

Whether the association is intramural or extramural depends upon who owns the two objects.

Storing Items in the Repository

As About Registries and Repositories explains, the Registry includes a repository in which you can store electronic content. For every item you store in the repository, you must first create a type of RegistryObject called an ExtrinsicObject. When you save the ExtrinsicObject to the Registry, the associated repository item is also saved.

Creating an Extrinsic Object

To create an ExtrinsicObject, you first need to create a javax.activation.DataHandler object for the repository item. The LifeCycleManager.createExtrinsicObject method takes a DataHandler argument.

To store a file in the repository, for example, first create a java.io.File object. From the File object, create a javax.activation.FileDataSource object, which you use to instantiate the DataHandler object. 

String filename = "./MyFile.xml";
File repositoryItemFile = new File(filename);
DataHandler repositoryItem = 
  new DataHandler(new FileDataSource(repositoryItemFile));

Next, call createExtrinsicObject with the DataHandler as argument: 

ExtrinsicObject eo = 
  blcm.createExtrinsicObject(repositoryItem);
eo.setName("My File");

Set the MIME type of the object to make it accessible. The default MIME type is application/octet-stream. If the file is an XML file, set it as follows: 

eo.setMimeType("text/xml");

Finally, call the implementation-specific ExtrinsicObjectImpl.setObjectType method to store the ExtrinsicObject in an appropriate area of the Registry. This method has the following signature: 

public void setObjectType(Concept objectType)
  throws JAXRException

The easiest way to find the appropriate concept for a file is to use the Explore feature of the Web Console. Look under the ObjectType classification scheme for the various types of ExtrinsicObject concepts. Specify the ID for the concept as the argument to getRegistryObject, then specify the concept as the argument to setObjectType. 

String conceptId = 
  "urn:oasis:names:tc:ebxml-
regrep:ObjectType:RegistryObject:ExtrinsicObject:XML";
Concept objectTypeConcept = 
  (Concept) bqm.getRegistryObject(conceptId);
((ExtrinsicObjectImpl)eo).setObjectType(objectTypeConcept);

Finally, you save the ExtrinsicObject to the Registry. 

Collection extobjs = new ArrayList();
extobjs.add(eo);
BulkResponse response = blcm.saveObjects(extobjs);

The ExtrinsicObject contains the metadata, and a copy of the file is stored in the repository.

If the Registry does not have a concept for the kind of file you want to store there, you can create and save the concept yourself.

Creating an Extrinsic Object: Example

For an example of creating an extrinsic object, see <INSTALL>/registry/samples/publish-extrinsic/src/JAXRPublishExtrinsicObject.java. This example publishes an XML file to the Registry. To run the example, follow these steps:

  1. Go to the directory <INSTALL>/registry/samples/publish-extrinsic.
  2. Type the following command:

    3. ant run

Using an Extrinsic Object as a Specification Link

You can publish an ExtrinsicObject by itself, but it is also very common to create an ExtrinsicObject to use as the SpecificationLink object for a ServiceBinding object (see Creating Services and Service Bindings). The ExtrinsicObject typically refers to a WSDL file.

  1. Create a SpecificationLink object.
  2. Store the WSDL document in the repository and create an ExtrinsicObject that refers to it. Set the extrinsic object's type to WSDL and its mime type to text/xml.
  3. Specify the extrinsic object as the specificationObject attribute of the SpecificationLink object.
  4. Add the SpecificationLink object to the ServiceBinding object.
  5. Add the ServiceBinding object to the Service object.
  6. Save the Service object.

After you create a Service and ServiceBinding, create a SpecificationLink: 

SpecificationLink specLink = blcm.createSpecificationLink();
specLink.setName("Spec Link Name");
specLink.setDescription("Spec Link Description");

Create an ExtrinsicObject as described in Creating an Extrinsic Object. Use the ID for the WSDL concept and the text/xml MIME type. 

String conceptId = 
  "urn:oasis:names:tc:ebxml-
regrep:ObjectType:RegistryObject:ExtrinsicObject:WSDL";
Concept objectTypeConcept = 
  (Concept) bqm.getRegistryObject(conceptId);
((ExtrinsicObjectImpl)eo).setObjectType(objectTypeConcept);
eo.setMimeType("text/xml");

Set the ExtrinsicObject as the specification object for the SpecificationLink: 

specLink.setSpecificationObject(eo);

Add the SpecificationLink to the ServiceBinding, then add the objects to their collections and save the services. 

binding.addSpecificationLink(specLink);
serviceBindings.add(binding);
...

When you remove a service from the Registry, the service bindings and specification links are also removed. However, the extrinsic objects associated with the specification links are not removed.

Creating an Extrinsic Object as a Specification Link: Example

For an example of creating an extrinsic object as a specification link, see <INSTALL>/registry/samples/publish-service/src/JAXRPublishService.java. This example publishes a WSDL file to the Registry. To run the example, follow these steps:

  1. Go to the directory <INSTALL>/registry/samples/publish-service.
  2. Type the following command:

    3. ant run

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. For example, you could create a RegistryPackage object and add to it all objects in the Registry whose names shared a particular unique string or that all contained a Slot with the same name and value.

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 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 load a file system into the Registry, storing the directories as registry packages and the files as the package contents. See the Administration Guide for more information.

Organizing Objects Within Registry Packages: Examples

For examples of using registry packages, see the two examples in <INSTALL>/registry/samples/packages/src: JAXRPublishPackage.java and JAXRQueryPackage.java. 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 examples, follow these steps:

  1. Go to the directory <INSTALL>/registry/samples/packages.
  2. Type the following command:

    3. ant pub-pkg

  3. Type the following command:

    4. ant query-pkg

Changing the State of Objects in the Registry

You add an AuditableEvent object to the audit trail of an object when you publish it to the Registry or when you modify it in any way. See Retrieving the Audit Trail of an Object for details on these events and on how to obtain information about them. Table 8-5 on page 33 describes the events and how they are created.

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

Note: At this release, versioning of objects is disabled. All objects have a version of 1.1.

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

It is possible to restrict access to these actions to specific users, such as registry administrators.

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. To run the examples, follow these steps:

  1. Go to the directory <INSTALL>/registry/samples/packages.
  2. Type the following command:

    3. ant approve-obj -Did=id_string

  3. Type the following command:

    4. ant deprecate-obj -Did=id_string

  4. Type the following command:

    5. ant undeprecate-obj -Did=id_string

The object you specify should be one that you created.

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 the user 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 does not delete the Service and User objects that belong to the Organization. You must delete them separately.

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

AuditableEvent and Association objects are not always deleted when the objects associated with them are deleted. You may 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 <INSTALL>/registry/samples/delete-object/src/JAXRDelete.java. This example deletes the object whose unique identifier you specify. To run the example, follow these steps:

  1. Go to the directory <INSTALL>/registry/samples/delete-object.
  2. Type the following command:

    3. ant run -Did=id_string