Understanding Join Conditions

Introduction

Join conditions are conditions that associate two or more document types with a single trigger service. Typically, join conditions are used to combine data published by different sources and process it with one service.

Join Types

The join type that you specify for a join condition determines whether Integration Server needs to receive all, any, or only one of the documents to execute the trigger service. The following table describes the join types that you can specify for a condition.

Join Type	Description
All (AND)	Integration Server invokes the associated trigger service when the server receives an instance of each specified publishable document type within the join time-out period. The instance documents must have the same activation ID. This is the default join type. For example, suppose that a join condition specifies document types documentA and documentB and documentC. Instances of all the document types must be received to satisfy the join condition. Additionally, all documents must have the same activation ID and must be received before the specified join time-out elapses.
Any (OR)	Integration Server invokes the associated trigger service when it receives an instance of any one of the specified publishable document types. For example, suppose that the join condition specifies document types documentA or documentB or documentC. Only one of these documents is required to satisfy the join condition. Integration Server invokes the associated trigger service every time it receives a document of type documentA, documentB, or documentC. The activation ID does not matter. No time-out is necessary.
Only one (XOR)	Integration Server invokes the associated trigger service when it receives an instance of any of the specified document types. For the duration of the join time-out period, Integration Server discards (blocks) any instances of the specified publishable document types with the same activation ID. For example, suppose that the join condition specifies document types documentA or documentB or documentC. Only one of these documents is required to satisfy the join condition. It does not matter which one. Integration Server invokes the associated trigger service after it receives an instance of one of the specified document types. Integration Server continues to discard instances of any qualified document types with the same activation ID until the specified join time-out elapses. Tip: You can create an Only one (XOR) join condition that specifies only one publishable document type. For example, you can create a condition that specified documentA and documentA. This condition indicates that Integration Server should process one and only one documentA with a particular activation ID during the join time-out period. Integration Server discards any other documentA documents with the same activation ID as the first one received.

Subscribe Path for Documents that Satisfy a Join Condition

Integration Server processes documents that satisfy join conditions in almost the same way in which it processes documents for simple conditions. When Integration Server determines that a document satisfies an All (AND) join condition or an Only one (XOR) join condition, it uses a join manager and the ISInternal database to process and store the individual documents in the join condition.

The following sections provide more information about how Integration Server processes documents for join conditions.

Note: Integration Server processes documents that satisfy an Any (OR) condition in the same way that it processes documents that satisfy simple conditions.

The Subscribe Path for Documents that Satisfy an All (AND) Join Condition

When Integration Server receives a document that satisfies an All (AND) join condition, it stores the document and then waits for the remaining documents specified in the join condition. Integration Server invokes the trigger service if each of the following occurs:

The trigger receives an instance of each document specified in the join condition.
The documents have the same activation ID.
The documents arrive within the specified join time-out period.

The following diagram illustrates how Integration Server receives and processes documents for All (AND) join conditions. In the following example, trigger X contains an All (AND) join condition that specifies that documentA and documentB must be received for the trigger service to execute.

Figure 1. Subscribe path for documents that satisfy an All (AND) join condition

Step	Description
1	Integration Server requests documents for a trigger from the messaging provider.
2	Integration Server receives documents for the trigger, including documentA and documentB. Both documentA and documentB have the same activation ID.
3	Integration Server places documentA and documentB in the trigger’s queue on Integration Server.
4	Integration Server pulls documentA from the trigger queue and evaluates the document against the conditions in the trigger. Integration Server determines that documentA partially satisfies an All (AND) join condition. Integration Server moves documentA from the trigger queue to the join manager. Integration Server starts the join time-out period. Note: If exactly-once processing is configured for the trigger, Integration Server first determines whether the document is a copy of one already processed by the trigger. Integration Server continues processing the document only if the document is new.
5	The join manager saves documentA to the ISInternal database. Integration Server assigns documentA a status of “pending.” Integration Server returns an acknowledgement for the document to the messaging provider.
6	Integration Server pulls documentB from the trigger queue and evaluates the document against the conditions in the trigger. Integration Server determines that documentB partially satisfies an All (AND) join condition. Integration Server sends documentB from the trigger queue to the join manager.
7	The join manager determines that documentB has the same activation ID as documentA. Because the join time-out period has not elapsed, the All (AND) join condition is completed. The join manager delivers a join document containing documentA and documentB to the trigger service specified in the condition.
8	Integration Server executes the trigger service.
9	After the trigger service executes to completion (success or error), one of the following occurs: If the service executes successfully and documentB is guaranteed, Integration Server acknowledges receipt of documentB to the messaging provider. Integration Server then removes the copy of the documentA from the ISInternal database and removes the copy of documentB from the trigger queue. If a service exception occurs, the service ends in error and Integration Server rejects the join document. If documentB is guaranteed, Integration Server acknowledges receipt of documentB to the messaging provider. Integration Server then removes the copy of the documentA from the ISInternal database and removes the copy of documentB from the trigger queue. Integration Server sends an error notification document to the publisher. If the trigger service catches a transient error, wraps it, and re-throws it as an ISRuntimeException, then Integration Server waits for the length of the retry interval and re-executes the service using the original document as input. If Integration Server reaches the maximum number of retries and the trigger service still fails because of a transient error, Integration Server treats the last failure as a service error. For more information about retrying a trigger service, see webMethods Service Development Help. Note: A transient error is an error that arises from a condition that might correct itself later, such as a network issue or an inability to connect to a database.

Notes:

If the join time-out period elapses before the other documents specified in the join condition (in this case, documentB) arrive, the ISInternal database drops documentA.
If documentB had a different activation ID, the join manager would move documentB to the ISInternal database, where it would wait for a documentA with a matching activation ID.
If documentB arrived after the join time-out period started by the receipt of documentA had elapsed, documentB would not complete the join condition. The ISInternal database would have already discarded documentA when the join time-out period elapsed. The join manager would send documentB to the ISInternal database and wait for another documentA with the same activation ID. Integration Server would restart the join time-out period.
Integration Server returns acknowledgements for guaranteed documents only.
If a transient error occurs during document retrieval or storage, the audit subsystem sends the document to the logging database and assigns it a status of FAILED. You can use webMethods Monitor to find and resubmit documents with a FAILED status if the documents were published locally or received from Broker. For more information about using webMethods Monitor, see the webMethods Monitor documentation.
If a trigger service generates audit data on error and includes a copy of the input pipeline in the service log, you can use webMethods Monitor to re-invoke the trigger service at a later time. For more information about configuring services to generate audit data, see webMethods Service Development Help.
You can configure a trigger to suspend and retry at a later time if retry failure occurs. Retry failure occurs when Integration Server makes the maximum number of retry attempts and the trigger service still fails because of an ISRuntimeException. For more information about handling retry failure, see webMethods Service Development Help.

The Subscribe Path for Documents that Satisfy an Only one (XOR) Join Condition

When Integration Server receives a document that satisfies an Only one (XOR) condition, it executes the trigger service specified in the join condition. For the duration of the join time-out period, Integration Server discards documents if:

The documents are of the type specified in the join condition, and
The documents have the same activation ID as the first document that satisfied the join condition.

The following diagram illustrates how Integration Server receives and processes documents for Only one (XOR) join conditions. In the following example, trigger X contains an Only one (XOR) join condition that specifies that either documentA or documentB must be received for the trigger service to execute. Integration Server uses whichever document it receives first to execute the service. When the other document specified in the join condition arrives, Integration Server discards it.

Figure 2. Subscribe path for documents that satisfy an Only one (XOR) condition

Step	Description
1	Integration Server requests documents for the trigger from the messaging provider.
2	Integration Server receives documents for the trigger, including documentA and documentB. Both documentA and documentB have the same activation ID.
3	Integration Server places documentA and documentB in the trigger’s queue on Integration Server.
4	Integration Server pulls documentA from the trigger queue and evaluates the document against the conditions in the trigger. Integration Server determines that documentA satisfies an Only one (XOR) join condition. Integration Server moves documentA from trigger queue to the join manager. Integration Server starts the join time-out period. Note: If exactly-once processing is configured for the trigger, Integration Server first determines whether the document is a copy of one already processed by the trigger. Integration Server continues processing the document only if the document is new.
5	The join manager saves the state of the join for this activation in the ISInternal database. The state information includes a status of “complete”.
6	Integration Server completes the processing of documentA by executing the trigger service specified in the Only one (XOR) condition.
7	After the trigger service executes to completion (success or error), one of the following occurs: If the service executes successfully, Integration Server returns the server thread to the thread pool. If the documentA is guaranteed, Integration Server returns an acknowledgement to the messaging provider. Integration Server removes the copy of the document from the trigger queue. If a service exception occurs, the service ends in error and Integration Server rejects the document. If documentA is guaranteed, Integration Server returns an acknowledgement to the messaging provider. Integration Server removes the copy of the document from the trigger queue and sends the publisher an error document to indicate that an error has occurred. If the trigger service catches a transient error, wraps it, and re-throws it as an ISRuntimeException, Integration Server waits for the length of the retry interval and re-executes the service. If Integration Server reaches the maximum number of retries and the trigger service still fails because of a transient error, Integration Server treats the last failure as a service error. For more information about retrying a trigger service, see webMethods Service Development Help. Note: A transient error is an error that arises from a condition that might correct itself later, such as a network issue or an inability to connect to a database.
8	Integration Server pulls documentB from the trigger queue, and evaluates the document against the conditions in the trigger. Integration Server determines that documentB satisfies the Only one (XOR) join condition. Integration Server sends documentB from the trigger queue to the join manager.
9	The join manager determines that documentB has the same activation ID as documentA. Because the join time-out period has not elapsed, the Integration Server discards documentB. Integration Server returns an acknowledgement for documentB to the messaging provider.

Notes:

If documentB had a different activation ID, the join manager would move documentB to the ISInternal database and execute the trigger service specified in the Only one (XOR) join condition.
If documentB arrived after the join time-out period started by the receipt of documentA had elapsed, Integration Server would invoke the trigger service specified in the Only one (XOR) join condition and start a new time-out period.
Integration Server returns acknowledgements for guaranteed documents only.
If a transient error occurs during document retrieval or storage, the audit subsystem sends the document to the logging database and assigns it a status of FAILED. You can use webMethods Monitor to find and resubmit documents with a FAILED status if the documents were published locally or received from Broker. For more information about using webMethods Monitor, see the webMethods Monitor documentation.
If a trigger service generates audit data on error and includes a copy of the input pipeline in the service log, you can use webMethods Monitor to re-invoke the trigger service at a later time. For more information about configuring services to generate audit data, see webMethods Service Development Help.
You can configure a trigger to suspend and retry at a later time if retry failure occurs. Retry failure occurs when Integration Server makes the maximum number of retry attempts and the trigger service still fails because of an ISRuntimeException. For more information about handling retry failure, see webMethods Service Development Help.

Join Conditions in Clusters

A cluster is treated as an individual Integration Server and acts as such with the exception of a failover. Any Integration Server in a cluster can act as the recipient of a document that fulfills a join condition. If there is more than one document required to fulfill the join, any members of the cluster can receive the documents as long as the documents are received within the allocated time-out period.

A cluster failover occurs if a document that completes a join condition is received by an Integration Server, which then experiences a hardware failure. In such cases, if the document is guaranteed, the messaging provider will redeliver the document to another Integration Server within the cluster and the join condition will be fulfilled.

Each member of a cluster shares the same database for storing the join state.