From e98595bed3e3cbde2d2e5b89e7239dc3396aa036 Mon Sep 17 00:00:00 2001 From: Emil Ivov Date: Tue, 5 May 2009 12:54:29 +0000 Subject: [PATCH] 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 --- .../OperationSetInstantMessageTransform.java | 66 +++++++++++++ .../service/protocol/TransformLayer.java | 93 +++++++++++++++++++ 2 files changed, 159 insertions(+) create mode 100644 src/net/java/sip/communicator/service/protocol/OperationSetInstantMessageTransform.java create mode 100644 src/net/java/sip/communicator/service/protocol/TransformLayer.java 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 000000000..2ab9c1a20 --- /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. + *

+ * 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 TransformLayer that we'd like to add + * to our protocol provider. + */ + public void addTransformLayer(TransformLayer transformLayer); + + /** + * Adds transformLayer to the layers currrently used for message + * transformation in this provider and assigns the specified + * priotity to it. + * + * @param priority the priority/order index that we'd like to insert + * transportLayer at. + * @param transformLayer the layer we are registering + */ + public void addTransformLayer(int priority, TransformLayer transformLayer); + + /** + * Removes transformLayer 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 layer 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 true if layer is currently registered with this + * provider and false 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 000000000..683bc41ed --- /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 TransformLayer, when registered with + * OperationSetInstantMessageTransform would be passed all message + * events. The class looks a lot like a MessageListener 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 null in case + * the TransformLayer implementation determines that the message event + * should not be determined to the upper layers. + *

+ * 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 Message has been received. The method + * returns an instance of MessageReceivedEvent which in many cases + * would be different from the evt 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 MessageReceivedEvent containing the newly + * received message, its sender and other details. + * + * @return an instance of a (possibly new) MessageReceivedEvent + * instance containing the transformed message or null if the + * TransportLayer 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 + * MessageDeliveredEvent which in many cases would be different + * from the evt 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) MessageDeliveredEvent + * instance containing the transformed message or null if the + * TransportLayer 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 MessageFailedEvent + * The method returns an instance of + * MessageDeliveredEvent which in many cases would be different + * from the evt 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 MessageFailedEvent containing the ID of the + * message whose delivery has failed. + * + * @return an instance of a (possibly new) MessageDeliveredEvent + * instance containing the transformed message or null if the + * TransportLayer has determined that this message event should not + * be delivered to the upper layers. + */ + public MessageDeliveryFailedEvent + messageDeliveryFailed(MessageDeliveryFailedEvent evt); +}