001 /*
002 GRANITE DATA SERVICES
003 Copyright (C) 2013 GRANITE DATA SERVICES S.A.S.
004
005 This file is part of Granite Data Services.
006
007 Granite Data Services is free software; you can redistribute it and/or modify
008 it under the terms of the GNU Library General Public License as published by
009 the Free Software Foundation; either version 2 of the License, or (at your
010 option) any later version.
011
012 Granite Data Services is distributed in the hope that it will be useful, but
013 WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
014 FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public License
015 for more details.
016
017 You should have received a copy of the GNU Library General Public License
018 along with this library; if not, see <http://www.gnu.org/licenses/>.
019 */
020
021 package org.granite.messaging.jmf;
022
023 import java.io.IOException;
024 import java.io.ObjectInput;
025 import java.lang.reflect.Field;
026
027 import org.granite.messaging.jmf.codec.ExtendedObjectCodec;
028 import org.granite.messaging.jmf.reflect.Reflection;
029
030 /**
031 * The <tt>ExtendedObjectInput</tt> interface extends <tt>ObjectInput</tt> and add two methods that
032 * help dealing with class loading ({@link #getClassLoader()}) and field assignments
033 * ({@link #readAndSetField(Object, Field)}).
034 *
035 * <p>
036 * Implementation instances of this interface are passed as parameter to
037 * {@link ExtendedObjectCodec#decode(ExtendedObjectInput, Object)} method calls.
038 * </p>
039 *
040 * <p>
041 * Several methods of the <tt>ObjectInput</tt> interface are tagged as deprecated and should
042 * never be used within <tt>ExtendedObjectCodec.decode(...)</tt> calls (implementations must throw
043 * <tt>UnsupportedOperationException</tt> errors).
044 * </p>
045 *
046 * @author Franck WOLFF
047 *
048 * @see ExtendedObjectCodec
049 * @see ExtendedObjectOutput
050 * @see JMFDeserializer
051 * @see InputContext
052 */
053 public interface ExtendedObjectInput extends ObjectInput {
054
055 /**
056 * Return the {@link Reflection} registered in the global JMF {@link SharedContext}.
057 *
058 * @return A <tt>Reflection</tt> utility that can be used to load classes during the
059 * deserialization process.
060 */
061 Reflection getReflection();
062
063 String getAlias(String className);
064
065 /**
066 * Read the next data in the current input stream and set the given <tt>field</tt> of
067 * the given Object <tt>obj</tt> with this data. This method is only a convenient shortcut
068 * for reading data from the input stream and setting the value of a {@link Field} to this
069 * data without knowing its type.
070 *
071 * For example, given a field <tt>f1</tt> of type <tt>boolean</tt> (the primitive type) and
072 * a field <tt>f2</tt> of type <tt>int</tt> (the primitive type):
073 *
074 * <pre>
075 * in.readAndSetField(obj, f1);
076 * in.readAndSetField(obj, f2);
077 * </pre>
078 * is equivalent to:
079 * <pre>
080 * f1.setBoolean(obj, in.readBoolean());
081 * f2.setInt(obj, in.readInt());
082 * </pre>
083 *
084 * @param obj The instance of the class declaring the field.
085 * @param field The field to set with the read value.
086 *
087 * @throws IOException If any I/O error occur.
088 * @throws JMFEncodingException If read data isn't of expected type (ie. the type of the given field).
089 * @throws ClassNotFoundException If the class of a serialized object cannot be found.
090 * @throws IllegalAccessException If the field cannot be accessed.
091 */
092 void readAndSetField(Object obj, Field field) throws IOException, ClassNotFoundException, IllegalAccessException;
093
094 /**
095 * Should never be used with JMF {@link ExtendedObjectCodec}.
096 * Use {@link #readByte()} instead.
097 *
098 * @deprecated Implementation must throw a {@link UnsupportedOperationException} error.
099 */
100 @Deprecated
101 public int read() throws IOException;
102
103 /**
104 * Should never be used with JMF {@link ExtendedObjectCodec}.
105 * Use <tt>(byte[])</tt>{@link #readObject()} instead.
106 *
107 * @deprecated Implementation must throw a {@link UnsupportedOperationException} error.
108 */
109 @Deprecated
110 public int read(byte[] b) throws IOException;
111
112 /**
113 * Should never be used with JMF {@link ExtendedObjectCodec}.
114 * Use <tt>(byte[])</tt>{@link #readObject()} instead.
115 *
116 * @deprecated Implementation must throw a {@link UnsupportedOperationException} error.
117 */
118 @Deprecated
119 public int read(byte[] b, int off, int len) throws IOException;
120
121 /**
122 * Should never be used with JMF {@link ExtendedObjectCodec}.
123 * Use <tt>(byte[])</tt>{@link #readObject()} instead.
124 *
125 * @deprecated Implementation must throw a {@link UnsupportedOperationException} error.
126 */
127 @Deprecated
128 public void readFully(byte[] b) throws IOException;
129
130 /**
131 * Should never be used with JMF {@link ExtendedObjectCodec}.
132 * Use <tt>(byte[])</tt>{@link #readObject()} instead.
133 *
134 * @deprecated Implementation must throw a {@link UnsupportedOperationException} error.
135 */
136 @Deprecated
137 public void readFully(byte[] b, int off, int len) throws IOException;
138
139 /**
140 * Should never be used with JMF {@link ExtendedObjectCodec}.
141 * Use {@link #readUTF()} instead and parse the String.
142 *
143 * @deprecated Implementation must throw a {@link UnsupportedOperationException} error.
144 */
145 @Deprecated
146 public String readLine() throws IOException;
147
148 /**
149 * Should never be used with JMF {@link ExtendedObjectCodec}.
150 *
151 * @deprecated Implementation must throw a {@link UnsupportedOperationException} error.
152 */
153 @Deprecated
154 public int skipBytes(int n) throws IOException;
155
156 /**
157 * Should never be used with JMF {@link ExtendedObjectCodec}.
158 *
159 * @deprecated Implementation must throw a {@link UnsupportedOperationException} error.
160 */
161 @Deprecated
162 public long skip(long n) throws IOException;
163 }