Author: mriou
Date: Thu May 25 06:40:08 2006
New Revision: 409387
URL: http://svn.apache.org/viewvc?rev=409387&view=rev
Log:
Integration API addition (specified by Maciej Szefler).
Added:
incubator/ode/trunk/bpel-api/
incubator/ode/trunk/bpel-api/pom.xml
incubator/ode/trunk/bpel-api/src/
incubator/ode/trunk/bpel-api/src/main/
incubator/ode/trunk/bpel-api/src/main/java/
incubator/ode/trunk/bpel-api/src/main/java/org/
incubator/ode/trunk/bpel-api/src/main/java/org/apache/
incubator/ode/trunk/bpel-api/src/main/java/org/apache/ode/
incubator/ode/trunk/bpel-api/src/main/java/org/apache/ode/iapi/
incubator/ode/trunk/bpel-api/src/main/java/org/apache/ode/iapi/BpelEngine.java
incubator/ode/trunk/bpel-api/src/main/java/org/apache/ode/iapi/BpelEngineException.java
incubator/ode/trunk/bpel-api/src/main/java/org/apache/ode/iapi/BpelServer.java
incubator/ode/trunk/bpel-api/src/main/java/org/apache/ode/iapi/Content.java
incubator/ode/trunk/bpel-api/src/main/java/org/apache/ode/iapi/ContextException.java
incubator/ode/trunk/bpel-api/src/main/java/org/apache/ode/iapi/EndpointReference.java
incubator/ode/trunk/bpel-api/src/main/java/org/apache/ode/iapi/EndpointReferenceContext.java
incubator/ode/trunk/bpel-api/src/main/java/org/apache/ode/iapi/Message.java
incubator/ode/trunk/bpel-api/src/main/java/org/apache/ode/iapi/MessageExchange.java
incubator/ode/trunk/bpel-api/src/main/java/org/apache/ode/iapi/MessageExchangeContext.java
incubator/ode/trunk/bpel-api/src/main/java/org/apache/ode/iapi/MyRoleMessageExchange.java
incubator/ode/trunk/bpel-api/src/main/java/org/apache/ode/iapi/PartnerRoleMessageExchange.java
incubator/ode/trunk/bpel-api/src/main/java/org/apache/ode/iapi/Scheduler.java
incubator/ode/trunk/bpel-api/src/main/java/org/apache/ode/iapi/TwoWayIdempotent.svg
incubator/ode/trunk/bpel-api/src/main/java/org/apache/ode/iapi/TwoWayIdempotent.usd
incubator/ode/trunk/bpel-api/src/main/java/org/apache/ode/iapi/TwoWayReliable.svg
incubator/ode/trunk/bpel-api/src/main/java/org/apache/ode/iapi/TwoWayReliable.usd
incubator/ode/trunk/bpel-api/src/main/java/org/apache/ode/iapi/TwoWayUnreliable.svg
incubator/ode/trunk/bpel-api/src/main/java/org/apache/ode/iapi/TwoWayUnreliable.usd
incubator/ode/trunk/bpel-api/src/main/java/org/apache/ode/iapi/TwoWayWithTransactionPropagation.svg
incubator/ode/trunk/bpel-api/src/main/java/org/apache/ode/iapi/TwoWayWithTransactionPropagation.usd
incubator/ode/trunk/bpel-api/src/main/java/org/apache/ode/iapi/iapi.svg
incubator/ode/trunk/bpel-api/src/main/java/org/apache/ode/iapi/package.html
Modified:
incubator/ode/trunk/pom.xml
Added: incubator/ode/trunk/bpel-api/pom.xml
URL:
http://svn.apache.org/viewvc/incubator/ode/trunk/bpel-api/pom.xml?rev=409387&view=auto
==============================================================================
--- incubator/ode/trunk/bpel-api/pom.xml (added)
+++ incubator/ode/trunk/bpel-api/pom.xml Thu May 25 06:40:08 2006
@@ -0,0 +1,43 @@
+<!--
+ ~ Copyright 2006 The Apache Software Foundation.
+ ~
+ ~ Licensed under the Apache License, Version 2.0 (the "License");
+ ~ you may not use this file except in compliance with the License.
+ ~ You may obtain a copy of the License at
+ ~
+ ~ http://www.apache.org/licenses/LICENSE-2.0
+ ~
+ ~ Unless required by applicable law or agreed to in writing, software
+ ~ distributed under the License is distributed on an "AS IS" BASIS,
+ ~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ ~ See the License for the specific language governing permissions and
+ ~ limitations under the License.
+ -->
+
+<project>
+ <artifactId>ode-bpel-api</artifactId>
+ <name>ODE :: BPEL API</name>
+ <description>
+ Various BPEL APIs used.
+ </description>
+
+ <modelVersion>4.0.0</modelVersion>
+ <parent>
+ <groupId>ode</groupId>
+ <artifactId>ode</artifactId>
+ <version>0.1-SNAPSHOT</version>
+ </parent>
+ <groupId>ode</groupId>
+ <version>0.1-SNAPSHOT</version>
+ <dependencies>
+ <dependency>
+ <groupId>ode</groupId>
+ <artifactId>ode-utils</artifactId>
+ </dependency>
+
+ <dependency>
+ <groupId>wsdl4j</groupId>
+ <artifactId>wsdl4j</artifactId>
+ </dependency>
+ </dependencies>
+</project>
Added:
incubator/ode/trunk/bpel-api/src/main/java/org/apache/ode/iapi/BpelEngine.java
URL:
http://svn.apache.org/viewvc/incubator/ode/trunk/bpel-api/src/main/java/org/apache/ode/iapi/BpelEngine.java?rev=409387&view=auto
==============================================================================
---
incubator/ode/trunk/bpel-api/src/main/java/org/apache/ode/iapi/BpelEngine.java
(added)
+++
incubator/ode/trunk/bpel-api/src/main/java/org/apache/ode/iapi/BpelEngine.java
Thu May 25 06:40:08 2006
@@ -0,0 +1,52 @@
+package org.apache.ode.iapi;
+
+import javax.xml.namespace.QName;
+
+/**
+ * Interface exposing the BPEL "engine". Basically, this interface facilitates
+ * dropping off events for processing by the engine. It is expected that
+ * <em>all</em> of the methods of this interface are called only from a
+ * "transactional context" (i.e. a transaction is associated with the thread
+ * invoking the method). The exact nature of the transactional context is not
+ * specified, however it must be the same context that is used by the BPEL
+ * DAO layer implementation. If a method invoked from this interface throws
+ * an exception of any kind, then the current transaction <em>must</em> be
+ * rolled back.
+ */
+public interface BpelEngine {
+ /**
+ * Check whether the given endpoint reference corresponds to a "my role"
+ * partner link in some process deployed in the engine. This method is
+ * provided so that the integration layer can route to multiple BPEL engines.
+ * @param epr target endpoint reference
+ * @return <code>true</code> if the EPR corresponds to a my-role of an
+ * active proces, <code>false</code> otherwise.
+ */
+ boolean isMyRoleEndpoint(EndpointReference epr)
+ throws BpelEngineException;
+
+
+ /**
+ * Create a "my role" message exchange for invoking a BPEL process.
+ *
+ * @param epr endpoint reference
+ * @param operation name of the operation
+ * @return [EMAIL PROTECTED] MyRoleMessageExchange} the newly created
message
+ * exchange
+ */
+ MyRoleMessageExchange createMessageExchange(
+ EndpointReference epr,
+ String operation)
+ throws BpelEngineException;
+
+
+
+ /**
+ * Retrieve a message identified by the given identifer.
+ * @param mexId message exhcange identifier
+ * @return associated message exchange
+ */
+ MessageExchange getMessageExchange(String mexId);
+
+
+}
Added:
incubator/ode/trunk/bpel-api/src/main/java/org/apache/ode/iapi/BpelEngineException.java
URL:
http://svn.apache.org/viewvc/incubator/ode/trunk/bpel-api/src/main/java/org/apache/ode/iapi/BpelEngineException.java?rev=409387&view=auto
==============================================================================
---
incubator/ode/trunk/bpel-api/src/main/java/org/apache/ode/iapi/BpelEngineException.java
(added)
+++
incubator/ode/trunk/bpel-api/src/main/java/org/apache/ode/iapi/BpelEngineException.java
Thu May 25 06:40:08 2006
@@ -0,0 +1,20 @@
+package org.apache.ode.iapi;
+
+/**
+ * Exception thrown by the BPEL engine / BPEL server.
+ */
+public class BpelEngineException extends RuntimeException {
+
+ public BpelEngineException(String msg, Exception e) {
+ super(msg,e);
+ }
+
+ public BpelEngineException(Exception ex) {
+ super(ex);
+ }
+
+ public BpelEngineException(String string) {
+ super(string);
+ }
+
+}
Added:
incubator/ode/trunk/bpel-api/src/main/java/org/apache/ode/iapi/BpelServer.java
URL:
http://svn.apache.org/viewvc/incubator/ode/trunk/bpel-api/src/main/java/org/apache/ode/iapi/BpelServer.java?rev=409387&view=auto
==============================================================================
---
incubator/ode/trunk/bpel-api/src/main/java/org/apache/ode/iapi/BpelServer.java
(added)
+++
incubator/ode/trunk/bpel-api/src/main/java/org/apache/ode/iapi/BpelServer.java
Thu May 25 06:40:08 2006
@@ -0,0 +1,102 @@
+/*
+ * File: $RCSfile$
+ * Copyright: (C) 1999-2005 FiveSight Technologies Inc.
+ *
+ */
+package org.apache.ode.iapi;
+
+import java.io.IOException;
+import java.net.URI;
+
+import javax.xml.namespace.QName;
+
+/**
+ * Interface implemented by the BPEL server. Provides methods for
+ * life-cycle management.
+ */
+public interface BpelServer {
+
+ /**
+ * Configure the [EMAIL PROTECTED] BpelEngine} with a message-exchange
context. BPEL
+ * engine uses this context to initiate communication with external
+ * services.
+ * @see MessageExchangeContext
+ * @param mexContext [EMAIL PROTECTED] MessageExchangeContext} implementation
+ */
+ void setMessageExchangeContext(MessageExchangeContext mexContext)
+ throws BpelEngineException;
+
+ /**
+ * Configure the [EMAIL PROTECTED] BpelEngine} with a scheduler.
+ */
+ void setScheduler(Scheduler scheduler)
+ throws BpelEngineException;
+
+
+ /**
+ * Configure the [EMAIL PROTECTED] BpelEngine} with an endpoint-reference
(EPR) context.
+ * BPEL engine uses this context to EPRs.
+ * @see EndpointReferenceContext
+ * @param eprContext [EMAIL PROTECTED] EndpointReferenceContext}
implementation
+ */
+ void setEndpointReferenceContext(EndpointReferenceContext eprContext)
+ throws BpelEngineException;
+
+
+ /**
+ * Set the DAO connection factory. The DAO is used by the BPEL engine
+ * to persist information about active processes.
+ * @param daoCF [EMAIL PROTECTED] BpelDAOConnectionFactory} implementation.
+ */
+// TODO Specify a DAO layer
+// void setDaoConnectionFactory(BpelDAOConnectionFactory daoCF)
+// throws BpelEngineException;
+
+
+ /**
+ * Initialize the BPEL engine. The various contexts needed by the
+ * engine must be configured before this method is called.
+ */
+ void init()
+ throws BpelEngineException;
+
+ /**
+ * Start the BPEL engine. The BPEL engine will not execute process
+ * instances until it is started.
+ */
+ void start()
+ throws BpelEngineException;
+
+
+ /**
+ * Stop the BPEL engine: results in the cessation of process
+ * execution.
+ */
+ void stop()
+ throws BpelEngineException;
+
+
+
+ /**
+ * Called to shutdown the BPEL egnine.
+ */
+ void shutdown()
+ throws BpelEngineException;
+
+
+ /**
+ * Get the [EMAIL PROTECTED] BpelEngine} interface.
+ * @return [EMAIL PROTECTED] BpelEngine} implementation
+ */
+ BpelEngine getEngine();
+
+ QName deploy(URI deployURI) throws IOException;
+
+ void undeploy(QName pid);
+
+ void undeploy(URI deployURI);
+
+ // TODO Specify a management API
+// BpelManagementFacade getBpelManagementFacade();
+
+}
Added:
incubator/ode/trunk/bpel-api/src/main/java/org/apache/ode/iapi/Content.java
URL:
http://svn.apache.org/viewvc/incubator/ode/trunk/bpel-api/src/main/java/org/apache/ode/iapi/Content.java?rev=409387&view=auto
==============================================================================
--- incubator/ode/trunk/bpel-api/src/main/java/org/apache/ode/iapi/Content.java
(added)
+++ incubator/ode/trunk/bpel-api/src/main/java/org/apache/ode/iapi/Content.java
Thu May 25 06:40:08 2006
@@ -0,0 +1,13 @@
+package org.apache.ode.iapi;
+
+/**
+ * Opaque representation of content. Implementation provided by integration
+ * layer. In the engine, we don't manipulate content directly, so we
+ * don't care what this is. Excpetions are BPEL data manipulation activities
+ * (like ASSIGN) and expressions: implementations of these will have to be
+ * specific to content (via a ContentHandler mechanism).
+ * @todo define content handler mechanism
+ */
+public interface Content {
+
+}
Added:
incubator/ode/trunk/bpel-api/src/main/java/org/apache/ode/iapi/ContextException.java
URL:
http://svn.apache.org/viewvc/incubator/ode/trunk/bpel-api/src/main/java/org/apache/ode/iapi/ContextException.java?rev=409387&view=auto
==============================================================================
---
incubator/ode/trunk/bpel-api/src/main/java/org/apache/ode/iapi/ContextException.java
(added)
+++
incubator/ode/trunk/bpel-api/src/main/java/org/apache/ode/iapi/ContextException.java
Thu May 25 06:40:08 2006
@@ -0,0 +1,9 @@
+package org.apache.ode.iapi;
+
+/**
+ * Exception thrown by the integration layer.
+ *
+ */
+public class ContextException extends RuntimeException {
+
+}
Added:
incubator/ode/trunk/bpel-api/src/main/java/org/apache/ode/iapi/EndpointReference.java
URL:
http://svn.apache.org/viewvc/incubator/ode/trunk/bpel-api/src/main/java/org/apache/ode/iapi/EndpointReference.java?rev=409387&view=auto
==============================================================================
---
incubator/ode/trunk/bpel-api/src/main/java/org/apache/ode/iapi/EndpointReference.java
(added)
+++
incubator/ode/trunk/bpel-api/src/main/java/org/apache/ode/iapi/EndpointReference.java
Thu May 25 06:40:08 2006
@@ -0,0 +1,28 @@
+package org.apache.ode.iapi;
+
+import javax.xml.namespace.QName;
+
+import org.w3c.dom.Document;
+
+/**
+ * Encapsulation of an end-point reference. Implementation of this interface
+ * is provided by the integration layer. The implementing class <em>must</em>
+ * provide an implementation of the
+ * [EMAIL PROTECTED] java.lang.Object#equals(java.lang.Object)} method that
returns
+ * <code>true</code> if and only if the EPRs are equivalent.
+ */
+public interface EndpointReference {
+
+ public static final QName SERVICE_REF_QNAME =
+ new QName("http://schemas.xmlsoap.org/ws/2004/03/business-process/";,
"service-ref");
+
+ /**
+ * Convert the EPR to an XML representation. The XML
+ * structure is up to the integration layer. This method is
+ * used by the BPEL engine to persist EPR references in the
+ * database.
+ * TODO: avoid using DOM
+ * @param result destination for the generated XML
+ */
+ Document toXML();
+}
Added:
incubator/ode/trunk/bpel-api/src/main/java/org/apache/ode/iapi/EndpointReferenceContext.java
URL:
http://svn.apache.org/viewvc/incubator/ode/trunk/bpel-api/src/main/java/org/apache/ode/iapi/EndpointReferenceContext.java?rev=409387&view=auto
==============================================================================
---
incubator/ode/trunk/bpel-api/src/main/java/org/apache/ode/iapi/EndpointReferenceContext.java
(added)
+++
incubator/ode/trunk/bpel-api/src/main/java/org/apache/ode/iapi/EndpointReferenceContext.java
Thu May 25 06:40:08 2006
@@ -0,0 +1,25 @@
+package org.apache.ode.iapi;
+
+import org.w3c.dom.Element;
+
+/**
+ * Endpoint reference context: facililates the creation of
+ * [EMAIL PROTECTED] EndpointReference} objects.
+ *
+ */
+public interface EndpointReferenceContext {
+
+ /**
+ * Resolve an end-point reference from its XML representation. The
+ * nature of the representation is determined by the integration
+ * layer. The BPEL engine uses this method to reconstruct
+ * [EMAIL PROTECTED] EndpointReference} objects that have been persisted in
the
+ * database via [EMAIL PROTECTED]
EndpointReference#toXML(javax.xml.transform.Result)}
+ * method.
+ *
+ * @param XML representation of the EPR
+ * @return reconsistituted [EMAIL PROTECTED] EndpointReference}
+ */
+ EndpointReference resolveEndpointReference(Element epr);
+
+}
Added:
incubator/ode/trunk/bpel-api/src/main/java/org/apache/ode/iapi/Message.java
URL:
http://svn.apache.org/viewvc/incubator/ode/trunk/bpel-api/src/main/java/org/apache/ode/iapi/Message.java?rev=409387&view=auto
==============================================================================
--- incubator/ode/trunk/bpel-api/src/main/java/org/apache/ode/iapi/Message.java
(added)
+++ incubator/ode/trunk/bpel-api/src/main/java/org/apache/ode/iapi/Message.java
Thu May 25 06:40:08 2006
@@ -0,0 +1,49 @@
+/*
+ * File: $RCSfile$
+ * Copyright: (C) 1999-2005 FiveSight Technologies Inc.
+ *
+ */
+package org.apache.ode.iapi;
+
+import org.w3c.dom.Element;
+
+
+/**
+ * A representation of a WSDL-typed message. The implementation of this
+ * interface is provided by the integration layer.
+ *
+ * TODO: flush this out WRT Sybase requirements.
+ * TODO: should we provide meta-data through this interface or will that
+ * put an undue burden on the integration layer?
+ */
+public interface Message {
+
+ /**
+ * Get a message part.
+ * @param partName name of the part
+ * @return named [EMAIL PROTECTED]
+ */
+ Content getPart(String partName);
+
+ /**
+ * Set the message part.
+ * @param partName name of part
+ * @param content part content
+ */
+ void setMessagePart(String partName, Content content);
+
+ /**
+ * Set the message as an element. The name of the element is irrelevant,
+ * but it should have one child element for each message part.
+ * TODO: remove this, temporary hack.
+ */
+ void setMessage(Element msg);
+
+ /**
+ * Get the message as an element. The returned element will have one
+ * child element corresponding (and named after) each part in the message.
+ * TODO: remove this, temporary hack.
+ */
+ Element getMessage();
+
+}
Added:
incubator/ode/trunk/bpel-api/src/main/java/org/apache/ode/iapi/MessageExchange.java
URL:
http://svn.apache.org/viewvc/incubator/ode/trunk/bpel-api/src/main/java/org/apache/ode/iapi/MessageExchange.java?rev=409387&view=auto
==============================================================================
---
incubator/ode/trunk/bpel-api/src/main/java/org/apache/ode/iapi/MessageExchange.java
(added)
+++
incubator/ode/trunk/bpel-api/src/main/java/org/apache/ode/iapi/MessageExchange.java
Thu May 25 06:40:08 2006
@@ -0,0 +1,164 @@
+/*
+ * File: $RCSfile$
+ * Copyright: (C) 1999-2005 FiveSight Technologies Inc.
+ *
+ */
+package org.apache.ode.iapi;
+
+import javax.wsdl.Operation;
+import javax.wsdl.PortType;
+import javax.xml.transform.Source;
+
+/**
+ * A representation of a communication (message-exchange) between the BPEL
+ * BPEL engine and an external "partner".
+ */
+public interface MessageExchange {
+
+ /**
+ * Enumeration of message exchange patterns.
+ */
+ public enum MessageExchangePattern {
+ REQUEST_ONLY,
+ REQUEST_RESPONSE,
+ UNKNOWN
+ }
+
+ /**
+ * Enumeration of the possible states for the message exchange.
+ */
+ public enum Status {
+ /** The request is being sent to the "server" */
+ REQUEST,
+
+ /** Waiting for an asynchronous response from the "server" */
+ ASYNC,
+
+ /** The one way request has been sent to the server. */
+ ONE_WAY,
+
+ /** Processing the response received from the "server". */
+ RESPONSE,
+
+ /** Processing the fault received from the "server". */
+ FAULT,
+
+ /** Processing a failure. */
+ FAILURE,
+
+ /** Message exchange completed succesfully. */
+ COMPLETED_OK,
+
+ /** Message exchange completed with a fault. */
+ COMPLETED_FAULT,
+
+ /** Message exchange completed with a failure. */
+ COMPLETED_FAILURE,
+ }
+
+ /**
+ * Enumeration of the types of failures.
+ */
+ public enum FailureType {
+ INVALID_ENDPOINT,
+ UNKNOWN_ENDPOINT,
+ UNKNOWN_OPERATION,
+ COMMUNICATION_ERROR,
+ FORMAT_ERROR,
+ NO_RESPONSE,
+ OTHER
+ }
+
+ /**
+ * Get the message exchange identifier. This identifier should be globally
+ * unique as the BPEL engine may keep identifiers for extended periods of
+ * time.
+ * @return unique message exchange identifier
+ */
+ String getMessageExchangeId()
+ throws BpelEngineException;
+
+ /**
+ * Get the name of the operation (WSDL 1.1) / message exchange (WSDL 1.2?).
+ *
+ * @return name of the operation (WSDL 1.1) /message exchange (WSDL 1.2?).
+ */
+ String getOperationName()
+ throws BpelEngineException;
+
+
+ /**
+ * Get a reference to the end-point targeted by this message exchange.
+ * @return end-point reference for this message exchange
+ */
+ EndpointReference getEndpointReference()
+ throws BpelEngineException;
+
+
+ /**
+ * Return the type of message-exchange that resulted form this invocation
+ * (request only/request-respone). If a
+ * [EMAIL PROTECTED] MessageExchangePattern#REQUEST_RESPONSE}
message-exchange was
+ * created, then the caller should expect a response in the future.
+ * @return type of message exchange created by the invocation
+ */
+ MessageExchangePattern getMessageExchangePattern();
+
+ /**
+ * Create a message associated with this exchange.
+ * @return a new [EMAIL PROTECTED] Message}
+ */
+ Message createMessage();
+
+ boolean isTransactionPropagated()
+ throws BpelEngineException;
+
+ /**
+ * Get the message exchange status.
+ * @return
+ */
+ Status getStatus();
+
+ /**
+ * Get the request message.
+ * @return request message
+ */
+ Message getRequest();
+
+ /**
+ * Get the response message.
+ * @return response message (or null if not avaiable)
+ */
+ Message getResponse();
+
+ /**
+ * Get the fault type.
+ * @return fault type, or <code>null</code> if not available/applicable.
+ */
+ String getFault();
+
+ /**
+ * Get the fault resposne message.
+ * @return fault response, or <code>null</code> if not available/applicable.
+ */
+ Message getFaultResponse();
+
+ /**
+ * Get the operation description for this message exchange.
+ * It is possible that the description cannot be resolved, for example if
+ * the EPR is unknown or if the operation does not exist.
+ * TODO: How to get rid of the WSDL4j dependency?
+ * @return WSDL operation description or <code>null</code> if not availble
+ */
+ Operation getOperation();
+
+ /**
+ * Get the port type description for this message exchange.
+ * It is possible that the description cannot be resolved, for example if
+ * the EPR is unknown or if the operation does not exist.
+ * TODO: How to get rid of the WSDL4j dependency?
+ * @return WSDL port type description or <code>null</code> if not available.
+ */
+ PortType getPortType();
+
+ }
Added:
incubator/ode/trunk/bpel-api/src/main/java/org/apache/ode/iapi/MessageExchangeContext.java
URL:
http://svn.apache.org/viewvc/incubator/ode/trunk/bpel-api/src/main/java/org/apache/ode/iapi/MessageExchangeContext.java?rev=409387&view=auto
==============================================================================
---
incubator/ode/trunk/bpel-api/src/main/java/org/apache/ode/iapi/MessageExchangeContext.java
(added)
+++
incubator/ode/trunk/bpel-api/src/main/java/org/apache/ode/iapi/MessageExchangeContext.java
Thu May 25 06:40:08 2006
@@ -0,0 +1,84 @@
+/*
+ * File: $RCSfile$
+ * Copyright: (C) 1999-2005 FiveSight Technologies Inc.
+ *
+ */
+package org.apache.ode.iapi;
+
+
+/**
+ * <p>
+ * Context provided by the integration layer exposing partner communication
+ * to the BPEL engine. The BPEL engine may only invoke methods on this
+ * interface from a transactional context provided by the integration layer.
+ * </p>
+ *
+ * <p>
+ * The following partner communication scenarios are possible:
+ * <ol>
+ * <li>partner is a accessible via a reliable transport (e.g. JMS, WS-RM)</li>
+ * <li>partner is accessible via an unreliable transport (e.g. HTTP)</li>
+ * <li>partner participates in the transaction (e.g. WS-TX)</li>
+ * </ol>
+ * It is important to note that each usage scenario is identical from the
+ * point of view of the BPEL engine. However, the integration layer must
+ * handle each of these scenarios in a different manner. See the method
+ * documentation for details.
+ * </p>
+ */
+public interface MessageExchangeContext {
+
+ /**
+ * <p>Invoke a partner. This method is invoked by the BPEL engine when an
+ * <code><invoke></code> construct is encountered. The BPEL engine
+ * will only invoke this method from a transactional context. This method
+ * MUST NOT block for extended periods (as it is called from within a
+ * transaction): to this end, actual invocation may be deferred or a
+ * synchronous operation may be decomposed into two asynchronous "legs".
+ * The integration layer must provide a response to the message exchange
+ * via the [EMAIL PROTECTED] PartnerRoleMessageExchange#reply(Message)},
+ * [EMAIL PROTECTED] PartnerRoleMessageExchange#replyOneWayOk()},
+ * [EMAIL PROTECTED]
PartnerRoleMessageExchange#replyWithFailure(FailureType, String, Element)}
+ * [EMAIL PROTECTED] PartnerRoleMessageExchange#replyWithFault(String,
Message)},
+ * or [EMAIL PROTECTED] PartnerRoleMessageExchange#replyAsync()} methods.
</p>
+ *
+ * <p>Invocation of reliable, unreliable, and transactional transports
should
+ * be treated differently. A brief description of how each of these scenarios
+ * could be handled follows.</p>
+ *
+ * <p>Reliable transports are transports such as JMS or WS-RM. For these
+ * transports, the request should be enrolled in the current transaction.
This
+ * necessarily implies that the request is deferred until the transaction is
+ * committed. It follows that for reliable request-response invocations
+ * the response to the invocation will necessarily be processed in a
separate
+ * transaction. </p>
+ *
+ * <p>Unreliable transports are transports such as HTTP. For these
transports,
+ * where the operation is not idempotent it is typically required that "at
+ * most once" semantics are achieved. To this end the invocation could be
+ * noted and deferred until after the transaction is committed. </p>
+ *
+ * <p>Transactional transports are those transports that support transaction
+ * propagation. For these transports, the invocation can be processed
+ * immediately and the response provided to the engine via the
+ * [EMAIL PROTECTED] PartnerRoleMessageExchange#reply(Message)} method. </p>
+ *
+ * @param mex engine-provided partner role message exchange representation,
+ * this object is valid only for the duration of the transaction
+ * from which the [EMAIL PROTECTED]
#invokePartner(PartnerRoleMessageExchange)}
+ * method is invoked
+ * @throws ContextException if the port does not support the
+ * operation
+ */
+ void invokePartner(PartnerRoleMessageExchange mex)
+ throws ContextException;
+
+ /**
+ * Method used to asynchronously deliver to the integration layer the BPEL
+ * engine's response to an invocation that could not complete synchronously.
+ * @see MyRoleMessageExchange#invoke(Message)
+ */
+ void onAsyncReply(MyRoleMessageExchange myRoleMex)
+ throws BpelEngineException;
+
+}
Added:
incubator/ode/trunk/bpel-api/src/main/java/org/apache/ode/iapi/MyRoleMessageExchange.java
URL:
http://svn.apache.org/viewvc/incubator/ode/trunk/bpel-api/src/main/java/org/apache/ode/iapi/MyRoleMessageExchange.java?rev=409387&view=auto
==============================================================================
---
incubator/ode/trunk/bpel-api/src/main/java/org/apache/ode/iapi/MyRoleMessageExchange.java
(added)
+++
incubator/ode/trunk/bpel-api/src/main/java/org/apache/ode/iapi/MyRoleMessageExchange.java
Thu May 25 06:40:08 2006
@@ -0,0 +1,76 @@
+package org.apache.ode.iapi;
+
+
+/**
+ * Extension of the [EMAIL PROTECTED] org.apache.ode.iapi.MessageExchange}
interface
+ * that is provided by the engine for message-exchanges where the engine
+ * acts as the server (i.e. where the engine is "invoked").
+ */
+public interface MyRoleMessageExchange extends MessageExchange {
+
+ /**
+ * Enumeration of message correlation results.
+ */
+ public enum CorrelationStatus {
+ /** The EPR is not associated with a process. */
+ UKNOWN_ENDPOINT,
+
+ /** The request resulted in the creation of a new instance. */
+ CREATE_INSTANCE,
+
+ /** The request was matched to an existing instance. */
+ MATCHED,
+
+ /** The request did not match an existing instance and was queued. */
+ QUEUED
+ }
+
+
+ /**
+ * Create a request message.
+ * @return
+ */
+ public Message createRequest();
+
+ /**
+ * Get the correlation state of the the invocation. An invocation will
+ * either create a new process instance, match an existing instance, or
+ * be queued for consumption by an instance in the future
+ * (see [EMAIL PROTECTED] CorrelationType} for details).
+ * @return correlation state of the invocation
+ */
+ public CorrelationStatus getCorrelationStatus();
+
+ /**
+ * "Invoke" a process hosted by the BPEL engine. The state of the invocation
+ * may be obtained by a call to the [EMAIL PROTECTED]
MessageExchange#getStatus()}
+ * method. It is possible that the response for the operation is not
+ * immediately available (i.e the call to [EMAIL PROTECTED]
#invoke(Message)} will
+ * return before a response is available). In such cases,
+ * [EMAIL PROTECTED] MessageExchange#getStatus()} == [EMAIL PROTECTED]
Status#ASYNC} and the
+ * integration layer will receive an asynchronous notification from
+ * the BPEL engine via the
+ * [EMAIL PROTECTED]
MessageExchangeContext#onAsyncReply(MyRoleMessageExchange)}
+ * when the response become available.
+ */
+ public void invoke(Message request);
+
+ /**
+ * Complete the message, exchange: indicates that the client has receive
+ * the response (if any).
+ */
+ public void complete();
+
+ /**
+ * Associate some arbitrary data with this message exchange.
+ * @param bs
+ */
+ public void setClientData(byte[] bs);
+
+ /**
+ * Get the previously associated client data for this exchange.
+ * @return
+ */
+ public byte[] getClientData();
+
+}
Added:
incubator/ode/trunk/bpel-api/src/main/java/org/apache/ode/iapi/PartnerRoleMessageExchange.java
URL:
http://svn.apache.org/viewvc/incubator/ode/trunk/bpel-api/src/main/java/org/apache/ode/iapi/PartnerRoleMessageExchange.java?rev=409387&view=auto
==============================================================================
---
incubator/ode/trunk/bpel-api/src/main/java/org/apache/ode/iapi/PartnerRoleMessageExchange.java
(added)
+++
incubator/ode/trunk/bpel-api/src/main/java/org/apache/ode/iapi/PartnerRoleMessageExchange.java
Thu May 25 06:40:08 2006
@@ -0,0 +1,56 @@
+package org.apache.ode.iapi;
+
+
+import org.w3c.dom.Element;
+
+public interface PartnerRoleMessageExchange extends MessageExchange {
+
+
+
+ /**
+ * Indicate that the partner faulted in processing the message exchange.
+ *
+ * @param faultType fault type
+ * @param outputFaultMessage the input message
+ *
+ * @throws IllegalStateException if delivering this type of message is
+ * inappropriate at the present point.
+ */
+ void replyWithFault(String faultType, Message outputFaultMessage)
+ throws BpelEngineException;
+
+ /**
+ * Indicate that the partner has responded to the message exchange.
+ *
+ * @param response the response from the partner
+ *
+ * @throws IllegalStateException if delivering this type of message is
+ * inappropriate at the present point.
+ */
+ void reply(Message response)
+ throws BpelEngineException;
+
+ /**
+ * Indicate that the partner has failed to process the message exchange.
+ *
+ * @param type type of failure
+ * @param description description of failure
+ */
+ void replyWithFailure(FailureType type, String description, Element details)
+ throws BpelEngineException;
+
+ /**
+ * Indicate that the partner processed the one-way invocation successfully.
+ */
+ void replyOneWayOk();
+
+ /**
+ * Indicate that the response to the request/response operation
+ * is not yet available and that the response will be delivered
+ * asynchronously.
+ */
+ void replyAsync();
+
+
+
+}
Added:
incubator/ode/trunk/bpel-api/src/main/java/org/apache/ode/iapi/Scheduler.java
URL:
http://svn.apache.org/viewvc/incubator/ode/trunk/bpel-api/src/main/java/org/apache/ode/iapi/Scheduler.java?rev=409387&view=auto
==============================================================================
---
incubator/ode/trunk/bpel-api/src/main/java/org/apache/ode/iapi/Scheduler.java
(added)
+++
incubator/ode/trunk/bpel-api/src/main/java/org/apache/ode/iapi/Scheduler.java
Thu May 25 06:40:08 2006
@@ -0,0 +1,41 @@
+package org.apache.ode.iapi;
+
+import java.util.Date;
+import java.util.Map;
+
+/**
+ * The BPEL scheduler.
+ */
+public interface Scheduler {
+
+ /**
+ * Schedule a persisted job. Persisted jobs MUST survive system failure.
+ * They also must not be scheduled unless the transaction associated with
+ * the calling thread commits.
+ * @param jobDetail information about the job
+ * @param when when the job should run (<code>null</code> means now)
+ * @return unique job identifier
+ */
+ String schedulePersistedJob(Map<String,Object>jobDetail,Date when);
+
+
+ /**
+ * Schedule a volatile (non-persisted) job. Volatile jobs should not be
+ * saved in the database and should not survive system crash. Volatile
+ * jobs scheduled from a transactional context should be scheduled
+ * regardless of whether the tansaction commits.
+ *
+ * @param jobDetail information about the job
+ * @param when when the job should run (<code>null</code> means now)
+ * @return unique (as far as the scheduler is concerned) job identifier
+ */
+ String scheduleVolatileJob(boolean transacted, Map<String,String> jobDetail,
Date when);
+
+ /**
+ * Make a good effort to cancel the job. If its already running no big
+ * deal.
+ * @param jobId job identifier of the job
+ */
+ void cancelJob(String jobId);
+
+}
