Adds interfaces that would allow future support of message trnasformation layers. These interfaces would remain unused until we spin off our 1.0 branch but I am commiting them now so that our George, our OTR GSoC student, could move on with his work. This is unlikely to have any impact on the rest of the code so we should be safe

2 files changed, 159 insertions, 0 deletions

diff --git a/src/net/java/sip/communicator/service/protocol/OperationSetInstantMessageTransform.java b/src/net/java/sip/communicator/service/protocol/OperationSetInstantMessageTransform.java
new file mode 100644
index 0000000..2ab9c1a
--- /dev/null
+++ b/src/net/java/sip/communicator/service/protocol/OperationSetInstantMessageTransform.java
@@ -0,0 +1,66 @@
+/*
+ * SIP Communicator, the OpenSource Java VoIP and Instant Messaging client.
+ *
+ * Distributable under LGPL license.
+ * See terms of license at gnu.org.
+ */
+package net.java.sip.communicator.service.protocol;
+
+/**
+ * The Instant Message Transform operation set allows, when \
+ * supported to insert message transform layers that could change incoming
+ * messages before they are delivered to the user and outgoing ones before
+ * they reach the protocol stack and get sent. One use case of this operation
+ * set is support of upper layer encryption mechanisms like OTR. Other cases may
+ * include hyperlink presentation, support for wiki words etc.
+ * <p/>
+ * Important Notice: As of May 5 2009, this operation set is still a work in
+ * progress and may change significantly in the following months. Any work based
+ * on this interface is therefore likely to require frequent updates to keep
+ * compatibility.
+ *
+ * @author Emil Ivov
+ *
+ */
+public interface OperationSetInstantMessageTransform
+{
+    /**
+     * Adds a transformation layer to this protocol provider using a default
+     * priority value.
+     *
+     * @param transformLayer the <tt>TransformLayer</tt> that we'd like to add
+     * to our protocol provider.
+     */
+    public void addTransformLayer(TransformLayer transformLayer);
+
+    /**
+     * Adds <tt>transformLayer</tt> to the layers currrently used for message
+     * transformation in this provider and assigns the specified
+     * <tt>priotity</tt> to it.
+     *
+     * @param priority the priority/order index that we'd like to insert
+     * <tt>transportLayer</tt> at.
+     * @param transformLayer the layer we are registering
+     */
+    public void addTransformLayer(int priority, TransformLayer transformLayer);
+
+    /**
+     * Removes <tt>transformLayer</tt> from the list of currently registered
+     * transform layers so that it won't be notified for further message events.
+     *
+     * @param transformLayer the layer we are trying to remove.
+     */
+    public void removeTransformLayer(TransformLayer transformLayer);
+
+    /**
+     * Determines whether <tt>layer</tt> is currently registered with this
+     * provider.
+     *
+     * @param layer the layer for which we'd like to know whether it is
+     * currently registered with this provider.
+     *
+     * @return <tt>true</tt> if <tt>layer</tt> is currently registered with this
+     * provider and <tt>false</tt> otherwise.
+     */
+    public boolean containsLayer(TransformLayer layer);
+}
diff --git a/src/net/java/sip/communicator/service/protocol/TransformLayer.java b/src/net/java/sip/communicator/service/protocol/TransformLayer.java
new file mode 100644
index 0000000..683bc41
--- /dev/null
+++ b/src/net/java/sip/communicator/service/protocol/TransformLayer.java
@@ -0,0 +1,93 @@
+/*
+ * SIP Communicator, the OpenSource Java VoIP and Instant Messaging client.
+ *
+ * Distributable under LGPL license.
+ * See terms of license at gnu.org.
+ */
+package net.java.sip.communicator.service.protocol;
+
+import net.java.sip.communicator.service.protocol.event.*;
+
+/**
+ * An instance of the <tt>TransformLayer</tt>, when registered with
+ * <tt>OperationSetInstantMessageTransform</tt> would be passed all message
+ * events. The class looks a lot like a <tt>MessageListener</tt> with the major
+ * difference being that all the methods are defined with a return value. The
+ * events we return would contain all message details after their transformation
+ * from by the layer implementation. All methods return <tt>null</tt> in case
+ * the <tt>TransformLayer</tt> implementation determines that the message event
+ * should not be determined to the upper layers.
+ * <p/>
+ * Important Notice: As of May 5 2009, this operation set is still a work in
+ * progress and may change significantly in the following months. Any work based
+ * on this interface is therefore likely to require frequent updates to keep
+ * compatibility.
+ *
+ * @author Emil Ivov
+ *
+ */
+public interface TransformLayer
+{
+    /**
+     * Called when a new incoming <tt>Message</tt> has been received. The method
+     * returns an instance of <tt>MessageReceivedEvent</tt> which in many cases
+     * would be different from the <tt>evt</tt> instance that was passed as
+     * param. The param and the return instances could very well (and will
+     * often) be instances of different implementations so users of this
+     * interface (i.e. protocol implementors) should make no assumptions
+     * for the class of the return type and copy the returned instance into
+     * a new one if necessary.
+     *
+     * @param evt the <tt>MessageReceivedEvent</tt> containing the newly
+     * received message, its sender and other details.
+     *
+     * @return an instance of a (possibly new) <tt>MessageReceivedEvent</tt>
+     * instance containing the transformed message or <tt>null</tt> if the
+     * <tt>TransportLayer</tt> has determined that this message event should not
+     * be delivered to the upper layers.
+     */
+    public MessageReceivedEvent messageReceived(MessageReceivedEvent evt);
+
+    /**
+     * Called when the underlying implementation has received an indication
+     * that a message, sent earlier has been successfully received by the
+     * destination. The method returns an instance of
+     * <tt>MessageDeliveredEvent</tt> which in many cases would be different
+     * from the <tt>evt</tt> instance that was passed as a parameter. The param
+     * and the return instances could very well (and will often) be instances of
+     * different implementations so users of this interface (i.e. protocol
+     * implementors) should make no assumptions for the class of the return type
+     * and copy the returned instance into a new one if necessary.
+     *
+     * @param evt the MessageDeliveredEvent containing the id of the message
+     * that has caused the event.
+     *
+     * @return an instance of a (possibly new) <tt>MessageDeliveredEvent</tt>
+     * instance containing the transformed message or <tt>null</tt> if the
+     * <tt>TransportLayer</tt> has determined that this message event should not
+     * be delivered to the upper layers.
+     */
+    public MessageDeliveredEvent messageDelivered(MessageDeliveredEvent evt);
+
+    /**
+     * Called to indicated that delivery of a message sent earlier has failed.
+     * Reason code and phrase are contained by the <tt>MessageFailedEvent</tt>
+     * The method returns an instance of
+     * <tt>MessageDeliveredEvent</tt> which in many cases would be different
+     * from the <tt>evt</tt> instance that was passed as a parameter. The param
+     * and the return instances could very well (and will often) be instances of
+     * different implementations so users of this interface (i.e. protocol
+     * implementors) should make no assumptions for the class of the return type
+     * and copy the returned instance into a new one if necessary.
+     *
+     * @param evt the <tt>MessageFailedEvent</tt> containing the ID of the
+     * message whose delivery has failed.
+     *
+     * @return an instance of a (possibly new) <tt>MessageDeliveredEvent</tt>
+     * instance containing the transformed message or <tt>null</tt> if the
+     * <tt>TransportLayer</tt> has determined that this message event should not
+     * be delivered to the upper layers.
+     */
+    public MessageDeliveryFailedEvent
+                        messageDeliveryFailed(MessageDeliveryFailedEvent evt);
+}