RegistryLookup node output

Use the RegistryLookup node to retrieve any type of entity held in the WebSphere® Service Registry and Repository (WSRR). The entities that match the specified search criteria are stored in the local environment. The input message is not modified.

Setting the Depth Policy property

The Depth Policy property on the RegistryLookup node specifies how much data is returned for each matched entity. The following table shows the valid values.
Depth Policy property value Local environment override value Data returned
Return matched only (Depth = 0) MatchOnly Just the matched entities
Return matched showing immediate relationships (For compatibility only) MatchShowRel The matched entities and additional references
Return matched plus immediate related entities (Depth = 1) MatchPlusImmediate The matched entities and the immediate related child entities
Return matched plus all related entities (Depth = -1) MatchPlusAll The matched entities and all the related child entities

Use MatchShowRel for compatibility with versions of WebSphere Message Broker before Version 6.1.0.4. The local environment output for MatchShowRel is shown in Example 1 and follows the format that was used in those previous versions. However, the MatchShowRel option is deprecated, and provided only for compatibility with previous versions. Do not use MatchShowRel if you are creating a new message flow, and consider migrating existing message flows to use one of the other options.

Use the MatchOnly option to retrieve just the individual entities matched by the search criteria. This option is efficient, however the local environment output does not contain any information about entities related to the matched entities.

Use the MatchPlusImmediate option to retrieve the entities matched by the search criteria, and the related child entities. This option offers a useful compromise, allowing you to access the immediate relations of the matched entities, while still restricting the total amount of data retrieved.

Use one of the MatchOnly or MatchPlusImmediate options when migrating a message flow that uses the deprecated MatchShowRel option. If your original message flow used the relationship information in the matched entities, use the MatchPlusImmediate option. See Migrating a message flow that uses the MatchShowRel option.

Use the MatchPlusAll option to retrieve the entities matched by the search criteria, and all the related child entities. Use this option only if your message flow needs access to more than the immediate relations of the matched entities, because it retrieves considerably more data than the MatchPlusImmediate option, see Local environment output tree.

Local environment output tree

The local environment output tree has a different format when the deprecated MatchShowRel option of the Depth Policy property is used. The following table describes the differences in the local environment output tree format.

MatchOnly, MatchPlusImmediate, and MatchPlusAll options MatchShowRel option
The ServiceRegistry folder element is owned by the XMLNSC compiler. No owning parser on the ServiceRegistry folder element, and each Entity element is owned by the XMLNS parser
The ServiceRegistry tree does not use unnecessary namespaces. Namespaces are attached to all UserDefined folder elements, meaning that the path specified must declare and use the relevant namespace to access fields within these folders.
The ServiceRegistry tree is optimized through use of the XMLNSC parser. The output tree contains a number of XML declaration, pcdata, and white space elements that have no business significance.
In WSRR, binary data is represented as a GenericDocument with a content attribute. The content attribute is represented in the local environment as XMLNSC type Attribute+base64Binary, (0x03000160). You can access the unencoded binary data directly as Entity.content. However, because of the special XMLNSC element type, the data is automatically base64 encoded if the tree is serialized. Binary content is represented as a base64 encoded character string in the content attribute. The message flow must invoke a Java™ method to decode the value if the original binary data is required.
The retrieved entities are not modified to add any user properties. The matched Entities appear in the local environment with a user property called WSRREncoding. This property has no specific significance to message flow processing. If there is a user property called WSRREncoding defined for the entity, the defined value is used, otherwise the WSRREncoding property is added with value="DEFAULT".
The MatchPlusImmediate and MatchPlusAll options result in a graph of entities being returned when WSRR executes the query. Each entity in the graph can refer to other entities. There are two types of relationship that cannot be expressed directly in a hierarchical tree:
  • Cyclic references - a graph can contain an entity from which you can follow relationships that arrive back at the same entity.
  • Multiple references - a graph can contain an entity that is referenced by multiple entities.
The representation of these relationships in the local environment output tree is described in the following text.
The WSRR graph is represented in the local environment output tree as follows:
  • The matched entities that are returned in the WSRR graph are represented as Entity elements as the first children of the LocalEnvironment.ServiceRegistry. The properties of the matched entities are represented as child elements.
  • A matched entity can contain references to other entities. If MatchPlusImmediate is set, these references are represented as Entity child elements of the matched entity. If MatchPlusAll is set, the same rule is applied recursively to these children.
  • Cyclic references - if an entity references another entity that is one of its ancestors in the WSRR graph, the referenced entity is represented as an EntityRef element. An EntityRef element does not represent the target entity directly, but provides information to identify it. This prevents the possibility of entering cyclic loops when navigating the tree.

    The following diagram shows references from entity D1 in the graph to entities C1 and A that are ancestral; therefore, Entity D1 in the message tree contains EntityRef elements for A and C1.

    Graph showing cyclic references, which are described in the surrounding text.
  • Multiple references - if an entity in the WSRR SDO graph is referenced by more than one other entity, it is represented as a separate Entity element in the message tree each time it is referenced. The Entity element is cloned, along with any entities that it refers to.

    The following diagram shows that entity X1 in the graph is referenced by entities Y1 and Y2, so Entity X1 and Entity W1 that it references are modeled twice in the message tree.

    Graph showing multiple references

Migrating a message flow that uses the MatchShowRel option

When you migrate an existing message flow that uses the deprecated MatchShowRel option of the Depth Policy property, the local environment output tree will have a different format. The table shown earlier describes the differences in the local environment output tree formats, and indicates what you must modify in the message flow to access the data in the updated format; see Local environment output tree.

Examples

The following examples show typical output from the RegistryLookup node:
  • Example 1 shows the full RegistryLookup node output in two cases for a query that returns two versions of a concept entity. In both cases the Match Policy property is set to All. In the first case the Depth Policy property is set to Return matched plus immediate related entities (Depth = 1) , and in the second case the Depth Policy property is set to Return matched only, showing immediate relationships (For compatibility only). This example also shows example ESQL to read elements of the output. See RegistryLookup node output: example 1
  • Example 2 shows the structure of RegistryLookup node output for all possible values of the Depth Policy property for a query on a concept entity that has a number of user relationships to other concept entities. See RegistryLookup node output: example 2
  • Example 3 shows the structure of RegistryLookup node output for a query on an entity having metadata relationships and user-defined relationships, using a Depth Policy property value of Return matched plus all related entities (Depth = -1) . See RegistryLookup node output: example 3.