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