Setting the Depth Policy property
| 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". |
- 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 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.
- 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.
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
- 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.
Last updated Friday, 21 July 2017