ClassificationScheme | Java Web Services in a Nutshell

ClassificationScheme

javax.xml.registry.infomodel

JAXR 1.0; JWSDP 1.0, J2EE 1.4

 public interface ClassificationScheme extends RegistryEntry {  // Public Constants  public static final int VALUE_TYPE_EMBEDDED_PATH;  //=1  public static final int VALUE_TYPE_NON_UNIQUE;  //=2  public static final int VALUE_TYPE_UNIQUE;  //=0   // Property Accessor Methods (by property name)  public abstract int getChildConceptCount(  )         throws javax.xml.registry.JAXRException;  //L0  public abstract Collection getChildrenConcepts(  )         throws javax.xml.registry.JAXRException;  //L0  public abstract Collection getDescendantConcepts(  )         throws javax.xml.registry.JAXRException;  //L0  public abstract boolean isExternal(  )         throws javax.xml.registry.JAXRException;  //L0  public abstract int getValueType(  )         throws javax.xml.registry.JAXRException;  //L1  public abstract void setValueType(int   valueType   )        throws javax.xml.registry.JAXRException;  //L1   // Public Instance Methods  public abstract void addChildConcept(Concept   concept   )        throws javax.xml.registry.JAXRException;  //L0  public abstract void addChildConcepts(Collection   concepts   )        throws javax.xml.registry.JAXRException;  //L0  public abstract void removeChildConcept(Concept   concept   )        throws javax.xml.registry.JAXRException;  //L0  public abstract void removeChildConcepts(Collection   concepts   )        throws javax.xml.registry.JAXRException;  //L0  }

A ClassificationScheme represents a hierarchy of related classifications that can be used to categorize objects in a registry. There are several commonly used classification schemes, such as NAICS, ISO-3166, and UNSPSC, that can be used to describe a business or service in various different ways. The NAICS scheme, for example, is used to categorize objects by their business type, such as "Book Publisher," whereas the ISO-3166 is used to denote geographical location. By associating elements of both schemes (represented in the JAXR model by Classification objects) with a business, it is possible to indicate that your Organization is a U.S.-based book publisher in such a way that potential clients could search for items tagged with these attributes.

A ClassificationScheme is hierarchical, with broader classifications appearing toward the root of the hierarchy and more specific ones toward the leaf nodes. The structure of the hierarchy may be known to the registry and represented as a hierarchy of Concept s, in which each Concept represents a single classification node. Such a ClassificationScheme is referred to as an internal scheme. An internal scheme has the advantage that you can use the JAXR API to navigate the Concept hierarchy to find out what classifications are available, and you can check whether a classification that claims to be within the scheme actually exists. By contrast, an external ClassificationScheme 's existence is known to the registry, but its structure is not. As a result, the registry cannot check whether classifications that claim to be part of an external scheme are valid, and cannot provide a way to discover all of the valid classifications.

You can use the findClassificationSchemes( ) and findClassificationSchemeByName( ) methods of BusinessLifeCycleManager to look up a ClassificationScheme , as the following code extract illustrates for the NAICS scheme:

 ClassificationScheme naics = bqm.findClassificationSchemeByName(null,  "%naics%");

To create a new scheme, use one of the createClassificationScheme( ) methods of LifeCycleManager :

 ClassificationScheme myScheme = blcm. createClassificationSchemeByName("MyScheme", "My Private Scheme");

If your scheme is going to be internal, you need to create the Concept s that represent the classification nodes and link them together to form the required structure. The top-level nodes can then be added to the ClassificationScheme using the addChildConcept( ) or addChildConcepts( ) methods. You can navigate the structure of an internal scheme using its getChildrenConcepts( ) and getDescendentConcepts( ) methods, together with the methods of Concept that allow its children and parents to be discovered . An external scheme has no internal structure known to the registry and therefore does not need to be constructed in the same way. Note that some registries, in particular the UDDI V2 registry, do not support the dynamic definition of internal classification schemes so that, although you can use the JAXR API to build one, you cannot save it. JAXR providers are required instead to provide a client-side mechanism that simulates the existence of custom internal classification schemes, although the exact mechanism is implementation-dependent. The reference implementation uses an XML file to represent such a classification scheme, as described in Chapter 7. Custom internal classification schemes can be created and stored in an ebXML registry as just described.

The getValueType( ) and setValueType( ) methods can be used to get and set an attribute that describes the value parts of the nodes in the scheme hierarchy. The following values are defined:

VALUE_TYPE_UNIQUE: Each node in the ClassificationScheme hierarchy has a unique value.
VALUE_TYPE_NON_UNIQUE: More than one node in the hierarchy may have the same value, although any two nodes belonging to the same parent must still have distinct values. As a result, to uniquely identify a classification within such a scheme, you may need the entire path from the node to the root.
VALUE_TYPE_EMBEDDED_PATH: The value embeds the path from its node to the root of the scheme. This guarantees , of course, that the value is unique.

Passed To

javax.xml.registry.LifeCycleManager.{createClassification( ) , createExternalIdentifier( )} , Classification.setClassificationScheme( ) , ExternalIdentifier.setIdentificationScheme( ) , PostalAddress.setPostalScheme( )

Returned By

javax.xml.registry.BusinessQueryManager.findClassificationSchemeByName( ) , javax.xml.registry.LifeCycleManager.createClassificationScheme( ) , javax.xml.registry.RegistryService.getDefaultPostalScheme( ) , Classification.getClassificationScheme( ) , Concept.getClassificationScheme( ) , ExternalIdentifier.getIdentificationScheme( ) , PostalAddress.getPostalScheme( )