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 import java.lang.reflect.InvocationTargetException;
027
028 import org.granite.messaging.jmf.codec.ExtendedObjectCodec;
029 import org.granite.messaging.reflect.Property;
030 import org.granite.messaging.reflect.Reflection;
031
032 /**
033 * The <tt>ExtendedObjectInput</tt> interface extends <tt>ObjectInput</tt> and add two methods that
034 * help dealing with reflection ({@link #getReflection()}) and field assignments
035 * ({@link #readAndSetProperty(Object, Property)}).
036 *
037 * <p>
038 * Implementation instances of this interface are passed as parameter to
039 * {@link ExtendedObjectCodec#decode(ExtendedObjectInput, Object)} method calls.
040 * </p>
041 *
042 * <p>
043 * Several methods of the <tt>ObjectInput</tt> interface are tagged as deprecated and should
044 * never be used within <tt>ExtendedObjectCodec.decode(...)</tt> calls (implementations must throw
045 * <tt>UnsupportedOperationException</tt> errors).
046 * </p>
047 *
048 * @author Franck WOLFF
049 *
050 * @see ExtendedObjectCodec
051 * @see ExtendedObjectOutput
052 * @see JMFDeserializer
053 * @see InputContext
054 */
055 public interface ExtendedObjectInput extends ObjectInput {
056
057 /**
058 * Return the {@link Reflection} registered in the global JMF {@link SharedContext}.
059 *
060 * @return A <tt>Reflection</tt> utility that can be used to load classes during the
061 * deserialization process.
062 */
063 Reflection getReflection();
064
065 String getAlias(String className);
066
067 /**
068 * Read the next data in the current input stream and set the given <tt>field</tt> of
069 * the given Object <tt>obj</tt> with this data. This method is only a convenient shortcut
070 * for reading data from the input stream and setting the value of a {@link Field} to this
071 * data without knowing its type.
072 *
073 * For example, given a field <tt>f1</tt> of type <tt>boolean</tt> (the primitive type) and
074 * a field <tt>f2</tt> of type <tt>int</tt> (the primitive type):
075 *
076 * <pre>
077 * in.readAndSetProperty(obj, f1);
078 * in.readAndSetProperty(obj, f2);
079 * </pre>
080 * is equivalent to:
081 * <pre>
082 * f1.setBoolean(obj, in.readBoolean());
083 * f2.setInt(obj, in.readInt());
084 * </pre>
085 *
086 * @param obj The instance of the class declaring the property.
087 * @param property The property to set with the read value.
088 *
089 * @throws IOException If any I/O error occur.
090 * @throws JMFEncodingException If read data isn't of expected type (ie. the type of the given property).
091 * @throws ClassNotFoundException If the class of a serialized object cannot be found.
092 * @throws IllegalAccessException If the property cannot be accessed.
093 */
094 void readAndSetProperty(Object obj, Property property) throws IOException, ClassNotFoundException, IllegalAccessException, InvocationTargetException;
095
096 /**
097 * Should never be used with JMF {@link ExtendedObjectCodec}.
098 * Use {@link #readByte()} instead.
099 *
100 * @deprecated Implementation must throw a {@link UnsupportedOperationException} error.
101 */
102 @Deprecated
103 public int read() throws IOException;
104
105 /**
106 * Should never be used with JMF {@link ExtendedObjectCodec}.
107 * Use <tt>(byte[])</tt>{@link #readObject()} instead.
108 *
109 * @deprecated Implementation must throw a {@link UnsupportedOperationException} error.
110 */
111 @Deprecated
112 public int read(byte[] b) throws IOException;
113
114 /**
115 * Should never be used with JMF {@link ExtendedObjectCodec}.
116 * Use <tt>(byte[])</tt>{@link #readObject()} instead.
117 *
118 * @deprecated Implementation must throw a {@link UnsupportedOperationException} error.
119 */
120 @Deprecated
121 public int read(byte[] b, int off, int len) throws IOException;
122
123 /**
124 * Should never be used with JMF {@link ExtendedObjectCodec}.
125 * Use <tt>(byte[])</tt>{@link #readObject()} instead.
126 *
127 * @deprecated Implementation must throw a {@link UnsupportedOperationException} error.
128 */
129 @Deprecated
130 public void readFully(byte[] b) throws IOException;
131
132 /**
133 * Should never be used with JMF {@link ExtendedObjectCodec}.
134 * Use <tt>(byte[])</tt>{@link #readObject()} instead.
135 *
136 * @deprecated Implementation must throw a {@link UnsupportedOperationException} error.
137 */
138 @Deprecated
139 public void readFully(byte[] b, int off, int len) throws IOException;
140
141 /**
142 * Should never be used with JMF {@link ExtendedObjectCodec}.
143 * Use {@link #readUTF()} instead and parse the String.
144 *
145 * @deprecated Implementation must throw a {@link UnsupportedOperationException} error.
146 */
147 @Deprecated
148 public String readLine() throws IOException;
149
150 /**
151 * Should never be used with JMF {@link ExtendedObjectCodec}.
152 *
153 * @deprecated Implementation must throw a {@link UnsupportedOperationException} error.
154 */
155 @Deprecated
156 public int skipBytes(int n) throws IOException;
157
158 /**
159 * Should never be used with JMF {@link ExtendedObjectCodec}.
160 *
161 * @deprecated Implementation must throw a {@link UnsupportedOperationException} error.
162 */
163 @Deprecated
164 public long skip(long n) throws IOException;
165 }