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 */
022package org.granite.messaging.jmf;
023
024import java.io.IOException;
025import java.io.ObjectInput;
026import java.lang.reflect.Field;
027import java.lang.reflect.InvocationTargetException;
028
029import org.granite.messaging.jmf.codec.ExtendedObjectCodec;
030import org.granite.messaging.reflect.Property;
031import 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 */
056public 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}