[asterisk-scf-commits] asterisk-scf/integration/slice.git branch "operation-context-propogation" created.
Commits to the Asterisk SCF project code repositories
asterisk-scf-commits at lists.digium.com
Mon Jan 23 08:48:00 CST 2012
branch "operation-context-propogation" has been created
at 4fe2a822210c32ba513739998a3807a2e89a67c4 (commit)
- Log -----------------------------------------------------------------
commit 4fe2a822210c32ba513739998a3807a2e89a67c4
Author: Brent Eagles <beagles at digium.com>
Date: Mon Jan 23 11:17:08 2012 -0330
Added OperationContext to some slices and marked several
idempotent. Comments and notes have been added (always a chance I might
have missed one or two.
diff --git a/slice/AsteriskSCF/SessionCommunications/SessionCommunicationsIf.ice b/slice/AsteriskSCF/SessionCommunications/SessionCommunicationsIf.ice
index b938374..2b3a304 100644
--- a/slice/AsteriskSCF/SessionCommunications/SessionCommunicationsIf.ice
+++ b/slice/AsteriskSCF/SessionCommunications/SessionCommunicationsIf.ice
@@ -20,6 +20,7 @@
#include <AsteriskSCF/Core/Routing/RoutingIf.ice>
#include <AsteriskSCF/System/Component/ComponentServiceIf.ice>
#include <AsteriskSCF/System/ExceptionsIf.ice>
+#include <AsteriskSCF/System/OperationsIf.ice>
#include <AsteriskSCF/System/Time/TimeIf.ice>
#include <AsteriskSCF/Media/MediaIf.ice>
#include <AsteriskSCF/SessionCommunications/TelephonyEventsIf.ice>
@@ -994,17 +995,23 @@ module V1
* Add a sequence of session proxies to the bridge. Sessions are started
* if necessary.
*
+ * @param operationContext Information about the logical operation context.
* @param session A sequence of session proxies.
*
* @throws InvalidSessions if any of the provided sessions are invalid.
+ * @throws BridgeSessionOperationFailed if any of the sessions could not be bridged.
+ * @throws OperationCallCancelledException if the operation needed to be cancelled.
*
* @see Session
* @see InvalidSessions
+ * @see AsteriskSCF::System::V1::OperationCallCancelledException
+ * @see AsteriskSCF::System::V1::OperationContext
*/
["amd"]
- void addSessions(
- SessionWithSessionInfoSeq sessionInfos)
- throws InvalidSessions, BridgeSessionOperationFailed;
+ idempotent void addSessions(AsteriskSCF::System::V1::OperationContext operationContext,
+ SessionWithSessionInfoSeq sessionInfos)
+ throws InvalidSessions, BridgeSessionOperationFailed,
+ AsteriskSCF::System::V1::OperationCallCancelledException;
/**
* Abruptly destroy the bridge. Sessions will not be stopped.
@@ -1022,16 +1029,21 @@ module V1
* Removes one or more sessions from the bridge. Sessions are not stopped
* as they are removed.
*
+ * @param operationContext Information about the logical operation context.
* @param sessions A sequence of session proxies.
*
* @throws InvalidSessions if any of the provided sessions are invalid.
+ * @throws OperationCallCancelledException if the operation needed to be cancelled.
*
* @see Session
* @see InvalidSessions
+ * @see AsteriskSCF::System::V1::OperationCallCancelledException
+ * @see AsteriskSCF::System::V1::OperationContext
*/
["amd"]
- void removeSessions(SessionSeq sessions)
- throws InvalidSessions, BridgeSessionOperationFailed;
+ idempotent void removeSessions(AsteriskSCF::System::V1::OperationContext operationContext, SessionSeq sessions)
+ throws InvalidSessions, BridgeSessionOperationFailed,
+ AsteriskSCF::System::V1::OperationCallCancelledException;
/**
* Nicely shutdown the bridge. Participating sessions are disconnected.
@@ -1039,29 +1051,50 @@ module V1
void shutdown();
/**
- * Adds a listener object to the bridge. The listener will receive notification
- * of future changes to the bridge as they occur.
+ * Adds a listener object to the bridge. The listener will receive notification of future changes to the bridge
+ * as they occur.
*
+ * Note: this operation needs an operation context to be declared idempotent because it a.) is a key part of
+ * call setup operations and all reasonable efforts must be made to ensure success and consistency and b.) the
+ * addition of a listener will likely result in side effects.
+ *
+ * @param operationContext Information about the logical operation context.
* @param listener A reference to a BridgeListener object.
*
+ * @throws OperationCallCancelledException if the operation needed to be cancelled.
+ *
* @see BridgeListener
+ * @see AsteriskSCF::System::V1::OperationCallCancelledException
+ * @see AsteriskSCF::System::V1::OperationContext
*/
- void addListener(BridgeListener* listener);
+ idempotent void addListener(AsteriskSCF::System::V1::OperationContext operationContext, BridgeListener* listener)
+ throws AsteriskSCF::System::V1::OperationCallCancelledException;
/**
- * Removes a listener object from the bridge. The listen will cease receiving
- * notifications of changes to the bridge.
+ * Removes a listener object from the bridge. The listener will cease receiving notifications of changes to the
+ * bridge.
+ *
+ * Note: this operation needs an operation context to be declared idempotent because it a.) is a key part of
+ * call setup operations and all reasonable efforts must be made to ensure success and consistency and b.) the
+ * addition of a listener will likely result in side effects.
*
+ * @param operationContext Information about the logical operation context.
* @param listener A reference to the listener object to be removed.
*
+ * @throws OperationCallCancelledException if the operation needed to be cancelled.
+ *
* @see BridgeListener
+ * @see AsteriskSCF::System::V1::OperationCallCancelledException
+ * @see AsteriskSCF::System::V1::OperationContext
*/
- void removeListener(BridgeListener* listener);
+ idempotent void removeListener(AsteriskSCF::System::V1::OperationContext opContext, BridgeListener* listener);
/**
* Replaces a session that is on the bridge with another session. Useful for transfers, etc.
* where a participant is replaced as part of the code flow.
*
+ * @param operationContext Information about the logical operation context.
+ *
* @param sessionToReplace The session being replaced. The bridge associated with this
* session is used for the newSessions.
*
@@ -1071,35 +1104,55 @@ module V1
* @throws InvalidSessions if any of the provided sessions are invalid.
*
* @throws SessionNotFound if the session to be replaced is not on the bridge.
+ *
+ * @throws OperationCallCancelledException if the operation needed to be cancelled.
+ *
+ * @see AsteriskSCF::System::V1::OperationCallCancelledException
+ * @see AsteriskSCF::System::V1::OperationContext
*/
["amd"]
- void replaceSession(Session* sessionToReplace,
+ idempotent void replaceSession(AsteriskSCF::System::V1::OperationContext operationContext, Session* sessionToReplace,
SessionWithSessionInfoSeq newSessionInfos)
- throws InvalidSessions, SessionNotFound, BridgeSessionOperationFailed;
+ throws InvalidSessions, SessionNotFound, BridgeSessionOperationFailed,
+ AsteriskSCF::System::V1::OperationCallCancelledException;
/**
* Set (or replace) cookies on the Bridge.
*
- * @param cookies A sequence of one or more concrete objects,
- * each of which are of a type derived from BridgeCookie. The
- * bridge will store these cookies on the bridge, replacing any
- * existing cookies with matching types.
+ * @param operationContext Information about the logical operation context.
+ *
+ * @param cookies A sequence of one or more concrete objects, each of which are of a type derived from
+ * BridgeCookie. The bridge will store these cookies on the bridge, replacing any existing cookies with
+ * matching types.
+ *
+ * @throws OperationCallCancelledException if the operation needed to be cancelled.
+ *
+ * @see AsteriskSCF::System::V1::OperationCallCancelledException
+ * @see AsteriskSCF::System::V1::OperationContext
*
* @note There can only be one cookie of a given type associated
* with a Bridge.
*/
- void setCookies(BridgeCookies cookies);
+ idempotent void setCookies(AsteriskSCF::System::V1::OperationContext operationContext, BridgeCookies cookies)
+ throws AsteriskSCF::System::V1::OperationCallCancelledException;
/**
* Remove cookies from the Bridge.
*
+ * @param operationContext Information about the logical operation context.
+ *
* @param cookies A sequence of one or more concrete objects,
* each of which are of a type derived from BridgeCookie.
* The bridge will remove any cookies on the bridge
* with types that match the ones in this sequence; the
* content of the supplied cookies is not compared.
+ *
+ * @throws OperationCallCancelledException if the operation needed to be cancelled.
+ *
+ * @see AsteriskSCF::System::V1::OperationCallCancelledException
+ * @see AsteriskSCF::System::V1::OperationContext
*/
- void removeCookies(BridgeCookies cookies);
+ idempotent void removeCookies(AsteriskSCF::System::V1::OperationContext operationContext, BridgeCookies cookies);
/**
* Get cookies stored on the Bridge.
@@ -1110,16 +1163,21 @@ module V1
* @return A sequence of zero or more cookies from the bridge,
* with types that match the types of the template cookies
* provided in the cookieTypes parameter.
+ *
+ * @note marked idempotent as it should not modify the contents of the target Ice object.
*/
- BridgeCookies getCookies(BridgeCookies cookieTypes);
+ idempotent BridgeCookies getCookies(BridgeCookies cookieTypes);
};
/**
- * Instances of BridgeListener are used for monitoring changes in one or
- * more bridges. Bridge objects have an addListener method that allows
- * BridgeListeners objects to be registered with the bridge. The Bridge
- * object then calls the BridgeListener methods to notify listeners of
- * changes as they occur.
+ * Instances of BridgeListener are used for monitoring changes in one or more bridges. Bridge objects have an
+ * addListener method that allows BridgeListeners objects to be registered with the bridge. The Bridge object then
+ * calls the BridgeListener methods to notify listeners of changes as they occur.
+ *
+ * @note an important aspect of the contract for listeners, they must handle duplicate calls of a particular
+ * operation. They are free to ignore subsequent requests. If one of the notifications represent a terminal state
+ * for the listener, it should respond to subsequent requests with an Ice::ObjectNotExistException or deactivate
+ * itself allowing the object adapter to do the work for them.
*/
interface BridgeListener
{
@@ -1132,7 +1190,7 @@ module V1
*
* @param cookies A sequence of bridge cookies that are associated with the bridge.
*/
- void sessionsAdded(Bridge* sessionBridge, SessionSeq sessions, BridgeCookies cookies);
+ idempotent void sessionsAdded(Bridge* sessionBridge, SessionSeq sessions, BridgeCookies cookies);
/**
* Called when sessions have been removed from a bridge.
@@ -1144,7 +1202,7 @@ module V1
*
* @param cookies A sequence of bridge cookies that are associated with the bridge.
*/
- void sessionsRemoved(Bridge* sessionBridge, SessionSeq sessions, BridgeCookies cookies);
+ idempotent void sessionsRemoved(Bridge* sessionBridge, SessionSeq sessions, BridgeCookies cookies);
/**
* Called when a bridge has completed shutdown/destruction.
@@ -1153,7 +1211,7 @@ module V1
*
* @param cookies A sequence of bridge cookies that are associated with the bridge.
*/
- void stopped(Bridge* sessionBridge, BridgeCookies cookies);
+ idempotent void stopped(Bridge* sessionBridge, BridgeCookies cookies);
/**
* Called when a bridge has started shutdown/destruction operations.
@@ -1162,7 +1220,7 @@ module V1
*
* @param cookies A sequence of bridge cookies that are associated with the bridge.
*/
- void stopping(Bridge* sessionBridge, BridgeCookies cookies);
+ idempotent void stopping(Bridge* sessionBridge, BridgeCookies cookies);
};
sequence<BridgeListener*> BridgeListenerSeq;
@@ -1187,19 +1245,27 @@ module V1
*
* @param listener A proxy to the bridge manager listener to add.
*/
- void addListener(BridgeManagerListener* listener);
+ idempotent void addListener(BridgeManagerListener* listener);
/**
* Method called to create a bridge.
*
+ * @param operationContext Information about the logical operation context.
+ *
* @param sessions A sequence of session proxies to be placed into the newly created bridge.
*
* @param listener A proxy to a bridge listener to be added to the newly created ridge.
*
* @return Bridge* Returns a proxy to the newly created bridge.
+ *
+ * @throws OperationCallCancelledException if the operation needed to be cancelled.
+ *
+ * @see AsteriskSCF::System::V1::OperationCallCancelledException
+ * @see AsteriskSCF::System::V1::OperationContext
+ *
*/
["amd"]
- Bridge* createBridge(Session* initiator,
+ idempotent Bridge* createBridge(Session* initiator,
SessionSeq destinations,
BridgeListener* listener,
AsteriskSCF::SessionCommunications::PartyIdentification::V1::Caller callerID,
@@ -1210,7 +1276,7 @@ module V1
*
* @param listener A proxy to the bridge manager listener to remove.
*/
- void removeListener(BridgeManagerListener* listener);
+ idempotent void removeListener(BridgeManagerListener* listener);
/**
* Method called to add a listener to the list of bridge listeners that
@@ -1221,7 +1287,7 @@ module V1
* @throws NullProxyException if the listener proxy is a null proxy.
*
*/
- void addDefaultBridgeListener(BridgeListener* listener)
+ idempotent void addDefaultBridgeListener(BridgeListener* listener)
throws AsteriskSCF::System::V1::NullProxyException;
/**
@@ -1233,7 +1299,7 @@ module V1
* @throws NullProxyException if the listener proxy is a null proxy.
*
*/
- void removeDefaultBridgeListener(BridgeListener* listener)
+ idempotent void removeDefaultBridgeListener(BridgeListener* listener)
throws AsteriskSCF::System::V1::NullProxyException;
/**
@@ -1245,8 +1311,14 @@ module V1
/**
* Method called to shut down the bridge manager.
+ *
+ * @note The shutdown operation is marked as idempotent as it really can be called repeatedly without
+ * damage. The first successful receipt of the operation should result in the object being "torn down". The
+ * target object should respond with ObjectNotExistException or simply ignore the request if it receives a
+ * repeat.
+ *
*/
- void shutdown();
+ idempotent void shutdown();
};
/**
@@ -1261,21 +1333,21 @@ module V1
*
* @param newBridge A proxy to the newly created bridge.
*/
- void bridgeCreated(BridgeManager* manager, Bridge* newBridge);
+ idempotent void bridgeCreated(BridgeManager* manager, Bridge* newBridge);
/**
* Notice that a bridge manager has stopped.
*
* @param manager The bridge manager that has stopped.
*/
- void stopped(BridgeManager* manager);
+ idempotent void stopped(BridgeManager* manager);
/**
* Notice that a bridge manager is stopping.
*
* @param manager The bridge manager that is stopping.
*/
- void stopping(BridgeManager* manager);
+ idempotent void stopping(BridgeManager* manager);
};
module Event
-----------------------------------------------------------------------
--
asterisk-scf/integration/slice.git
More information about the asterisk-scf-commits
mailing list