blob: f9615bdb2626c72e9ff7e88566a872b39c1e222f (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
|
/*
* Jitsi, 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 just been asked by other
* bundles to send an outgoing message. 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 a number of instances of (possibly new)
* <tt>MessageDeliveredEvent</tt> instances containing the transformed
* message(s) or an empty array if the <tt>TransportLayer</tt> has
* determined that there are no message event that should be delivered to
* the upper layers.
*/
public MessageDeliveredEvent[] messageDeliveryPending(MessageDeliveredEvent 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);
}
|
