MessageManager


1   /**
2    * Dream
3    * Copyright (C) 2003-2004 INRIA Rhone-Alpes
4    *
5    * This library is free software; you can redistribute it and/or
6    * modify it under the terms of the GNU Lesser General Public
7    * License as published by the Free Software Foundation; either
8    * version 2 of the License, or (at your option) any later version.
9    *
10   * This library is distributed in the hope that it will be useful,
11   * but WITHOUT ANY WARRANTY; without even the implied warranty of
12   * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
13   * Lesser General Public License for more details.
14   *
15   * You should have received a copy of the GNU Lesser General Public
16   * License along with this library; if not, write to the Free Software
17   * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
18   *
19   * Contact : dream@objectweb.org
20   *
21   * Initial developer(s): Matthieu Leclercq
22   * Contributor(s): Vivien Quema
23   */
24  
25  package org.objectweb.dream.message.manager;
26  
27  import org.objectweb.dream.message.ChunkType;
28  import org.objectweb.dream.message.Message;
29  import org.objectweb.dream.message.MessageType;
30  
31  /**
32   * A message manager is responsible for the life cycle of messages and chunks.
33   * This Interface is a component interface. Each Dream component has a
34   * <code>MessageManager</code> client interface (optionally bound).
35   */
36  public interface MessageManager
37  {
38  
39    /** The commonly used name of refer to this interface. */
40    String   ITF_NAME = "message-manager";
41  
42    /**
43     * Allocates and returns a message of the specified type. Depending on the
44     * implementation, the returned message is extensible (see
45     * {@link org.objectweb.dream.message.ExtensibleMessage}) or not.
46     * 
47     * @param type the type of the message to be created.
48     * @return a message.
49     * @throws UnknownChunkTypeError if one of the chunk type in the message type
50     *           is unknown by the manager (see {@link #createChunk(ChunkType)}).
51     */
52    Message createMessage(MessageType type) throws UnknownChunkTypeError;
53  
54    /**
55     * Deletes a message. If the message has been duplicated (by reference), this
56     * operation releases the given reference. The message is effectively deleted
57     * only if all its references have been released.
58     * 
59     * @param message the message to be deleted.
60     */
61    void deleteMessage(Message message);
62  
63    /**
64     * Duplicates a message. There are two kinds of duplication:
65     * <ul>
66     * <li>by <b>reference </b>. The returned Message is <i>the same object </i>
67     * than the given one. The manager keeps track of the number of message
68     * references, so that the {@link #deleteMessage(Message)}operation only
69     * deletes the message when all the duplicated references have been released
70     * </li>
71     * <li>by <b>value </b> (cloning). The returned message is a new message
72     * which contains a copy of each chunk and each enclosed message of the
73     * original message</li>
74     * </ul>
75     * 
76     * @param message the message to be duplicated.
77     * @param clone the duplication mode. <code>false</code> for reference
78     *          duplication, <code>true</code> for value duplication.
79     * @return the duplicated message.
80     */
81    Message duplicateMessage(Message message, boolean clone);
82  
83    /**
84     * Allocates and returns a chunk of the specified type. A given manager
85     * implementation knows only a restricted set of {@link ChunkType}, so if the
86     * requesed chunk type is unknown, a {@link UnknownChunkTypeError}is thrown
87     * 
88     * @param type the type of the chunk to be created.
89     * @return a chunk.
90     * @throws UnknownChunkTypeError if the chunk type can not be resolved by the
91     *           manager (cannot find implementation).
92     */
93    Object   createChunk(ChunkType type) throws UnknownChunkTypeError;
94  
95    /**
96     * Deletes a chunk. If the chunk has been duplicated (by reference), this
97     * operation releases the given reference. The chunk is effectively deleted
98     * only if all its references have been released.
99     * 
100    * @param chunk the chunk to delete.
101    */
102   void deleteChunk(Object   chunk);
103 
104   /**
105    * Duplicates a chunk. As for messages, there are two kinds of duplications
106    * (see {@link #duplicateMessage(Message, boolean)}).
107    * 
108    * @param chunk the chunk to be duplicated.
109    * @param clone the duplication mode.
110    * @return the duplicated chunk.
111    */
112   Object   duplicateChunk(Object   chunk, boolean clone);
113 
114   /**
115    * Returns the message manager identifier.
116    * 
117    * @return the message manager identifier.
118    */
119   short getMessageManagerId();
120 }
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags