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); +}