test

Service Registry 3 2005Q4 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

Steps

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

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


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


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

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 that you store in the repository, you must first create 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.

Note –

You can also use an implementation-specific form of the createExtrinsicObject method that takes no arguments. If you use this form, you can create the DataHandler object later and use the ExtrinsicObject.setRepositoryItem method to specify the repository item. You can also create extrinsic objects that have no associated repository items.

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 Graphics File");

Set the MIME type of the object to make the object accessible. The default MIME type is application/octet-stream. If the file is an XML file, set the MIME type 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 particular type of 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 that 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 JAXRPublishExtrinsicObject.java in the directory <INSTALL>/registry/samples/publish-extrinsic/src. This example publishes an XML file to the Registry (its own build.xml file).

ProcedureTo Run the JAXRPublishExtrinsicObject Example

Steps

  1. Go to the directory <INSTALL>/registry/samples/publish-extrinsic.

  2. Type the following command:


    asant run

Using an Extrinsic Object in a Specification Link

You can publish an ExtrinsicObject by itself, but it is also a common practice to create an ExtrinsicObject to use as the specificationObject attribute of a SpecificationLink 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 for Use in a Specification Link: Example

For an example of creating an extrinsic object to use in a specification link, see JAXRPublishService.java in the directory <INSTALL>/registry/samples/publish-service/src. This example publishes a WSDL file to the Registry.

ProcedureTo Run the JAXRPublishService Example

Steps

  1. Go to the directory <INSTALL>/registry/samples/publish-service.

  2. Type the following command:


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

Steps

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

  2. Type the following command:


    asant pub-pkg

  3. Type the following command:


    asant 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 any way. See Retrieving the Audit Trail of an Object for details on these events and on how to obtain information about them. Retrieving the Audit Trail of an Object describes the events and how they are created.

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

Note –

Versioning of objects is enabled by default when you publish using the JAXR API. Versioning is disabled by default when you publish using the Web Console.

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 = lcm.createKey(id);
Collection keys = new ArrayList();
keys.add(key);

// deprecate the object
lcm.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

Steps

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

  2. Type the following command:


    asant approve-obj -Did=id_string

  3. Type the following command:


    asant deprecate-obj -Did=id_string

  4. Type the following command:


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

Steps

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

  2. Type the following command:


    asant run -Did=id_string