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