Marshaller


1   /***
2    * Jonathan: an Open Distributed Processing Environment 
3    * Copyright (C) 1999 France Telecom R&D
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   * Release: 2.0
20   *
21   * Contact: jonathan@objectweb.org
22   *
23   * Author: Bruno Dumant
24   * 
25   */
26  
27  
28  package org.objectweb.jonathan.apis.presentation;
29  
30  import java.io.OutputStream  ;
31  
32  import org.objectweb.jonathan.apis.kernel.JonathanException;
33  import org.objectweb.jonathan.apis.kernel.Context;
34  import org.objectweb.jonathan.apis.resources.Chunk;
35  
36  /**
37   * Marshaller is the type of basic types marshallers. They should be used
38   * by protocols.
39   */
40  public interface Marshaller {
41  
42     /** 
43      * Writes a chunk in the message. 
44      * <p> 
45      * The target becomes the "owner" of the provided chunk, and therefore is not 
46      * supposed to duplicate it. If the entity invoking this operation wants to keep
47      * a reference to the chunk, it must be duplicated.
48      *
49      * @param chunk the chunk to be written.
50      */
51     void write(Chunk chunk);
52  
53  
54     /**
55      * Writes a byte.
56      * 
57      * @param b a byte;
58      * @exception JonathanException if a marshal error occurred.
59      */
60     void writeByte(byte b)
61        throws JonathanException;
62     
63     /**
64      * Writes a boolean.   
65      *
66      * @param b a boolean;
67      * @exception JonathanException if a marshal error occurred.
68      */
69     void writeBoolean(boolean b)
70        throws JonathanException;
71  
72     /**
73      * Writes an 8 bits char.
74      * <p>
75      * The method used to translate the provided <code>char</code> into an 8 bits 
76      * entity is not specified.
77      *
78      * @param i a char;
79      * @exception JonathanException if a marshal error occurred.
80      */
81     void writeChar8(char i)
82        throws JonathanException;   
83  
84     /**
85      * Writes a 16 bits char.
86      *
87      * @param i a char;
88      * @exception JonathanException if a marshal error occurred.
89      */
90     void writeChar16(char i)
91        throws JonathanException;   
92  
93     /**
94      * Writes a short.
95      *
96      * @param i a short;
97      * @exception JonathanException if a marshal error occurred.
98      */
99     void writeShort(short i)
100       throws JonathanException;
101 
102    /**
103     * Writes an int.
104     *
105     * @param i an int;
106     * @exception JonathanException if a marshal error occurred.
107     */
108    void writeInt(int i)
109       throws JonathanException;
110 
111    /**
112     * Writes a long.
113     *
114     * @param i a long;
115     * @exception JonathanException if a marshal error occurred.
116     */
117    void writeLong(long i)
118       throws JonathanException;
119 
120    /**
121     * Writes a float.
122     *
123     * @param f a float;
124     * @exception JonathanException if a marshal error occurred.
125     */
126    void writeFloat(float f)
127       throws JonathanException;
128 
129    /**
130     * Writes a double.
131     *
132     * @param d a double;
133     * @exception JonathanException if a marshal error occurred.
134     */
135    void writeDouble(double d)
136       throws JonathanException;
137 
138    /**
139     * Writes a string of 8 bits chars.
140     *
141     * @param s a string;
142     * @exception JonathanException if a marshal error occurred.
143     */
144    void writeString8(String   s)
145       throws JonathanException;
146    
147    /**
148     * Writes a string of 16  bits chars.
149     *
150     * @param s a string;
151     * @exception JonathanException if a marshal error occurred.
152     */
153    void writeString16(String   s)
154       throws JonathanException;
155 
156    /** 
157     * Writes an object reference in the marshaller.
158     *
159     * @param obj an object reference
160     * @exception JonathanException if a marshal error occurred.
161     */
162    void writeReference(Object   obj) throws JonathanException;
163 
164    /** 
165     * Writes a value in the marshaller.
166     *
167     * @param obj an object
168     * @exception JonathanException if a marshal error occurred.
169     * @since 3.0 a2
170     */
171    void writeValue(Object   obj) throws JonathanException;
172 
173    /**
174     * Writes an array of bytes.
175     *
176     * @param array an array of bytes;
177     * @param offset index of the first byte in array that must be written.
178     * @param length number of bytes of array that must be written.
179     * @exception JonathanException if a marshal error occurred.
180     */
181    void writeByteArray(byte[] array, int offset, int length)
182       throws JonathanException;
183 
184    
185    /** 
186     * Returns an output stream to write into the message. Closing the output stream
187     * has the same effect as closing the marshaller itself.
188     *
189     * @return an output stream to write into the message.
190     */
191    OutputStream   outputStream();
192 
193 
194    /** 
195     * Checks if the target marshaller and the provided one have the same contents, 
196     * i.e., they contain the same bits.
197     * 
198     * @param marshaller a marshaller;
199     * @return true if the target marshaller and the provided one have the same 
200     *              contents, false otherwise.
201     */
202    boolean sameContents(Marshaller marshaller);   
203 
204 
205    /**
206     * Returns true if this marshaller is little-endian, false otherwise.
207     *
208     * @return true if this marshaller is little-endian, false otherwise.
209     */
210    boolean isLittleEndian();
211 
212    /** 
213     * Returns the state of the message as a (chain of) chunk(s). 
214     * <p>
215     * The returned chunk(s) are NOT duplicated. If the caller keeps a
216     * reference to them, it must {@link #reset() reset} the message, and not 
217     * continue to use it.
218     * 
219     * @return the state of the message as a (chain of) chunk(s).
220     */
221    Chunk getState();
222 
223    /** 
224     * Returns the current offset in the message, i.e., the position in the message 
225     * at which the next byte will be written.
226     * 
227     * @return the current offset in the message.
228     */
229    int getOffset();
230 
231 
232    /** 
233     * Sets the offset in the message.
234     * <p>
235     * This method may be used to override data already written into the message.
236     * 
237     * @param offset the new offset.
238     */
239    void setOffset(int offset);
240 
241    /** 
242     * Returns a {@link Context Context} associated with this marshaller.
243     * @return a {@link Context Context} associated with this marshaller.
244     */
245    Context getContext();
246 
247    /** 
248     * This method causes the message to lose all its references to the underlying 
249     * chunks, without
250     * {@link org.objectweb.jonathan.apis.resources.Chunk#release() releasing}
251     * them. This method must not be used if no reference to chunks present in the
252     * message is held by an entity in charge of their release.   It also releases 
253     * the context associated with the target marshaller.
254     */
255    void reset();
256 
257 
258    /** 
259     * This method causes the message to lose all its references to the underlying 
260     * chunks, and
261     * {@link org.objectweb.jonathan.apis.resources.Chunk#release() release}  each
262     * of them. It also released the context.
263     */
264    void close();
265 
266 }
267 
268 
269
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags