1 /*
   2  * Copyright (c) 2003, 2014, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package javax.sql.rowset.serial;
  27 
  28 import java.sql.*;
  29 import java.io.*;
  30 import java.util.*;
  31 
  32 /**
  33  * A serialized mapping of a <code>Ref</code> object, which is the mapping in the
  34  * Java programming language of an SQL <code>REF</code> value.
  35  * <p>
  36  * The <code>SerialRef</code> class provides a constructor  for
  37  * creating a <code>SerialRef</code> instance from a <code>Ref</code>
  38  * object and provides methods for getting and setting the <code>Ref</code> object.
  39  *
  40  * <h3> Thread safety </h3>
  41  *
  42  * A SerialRef is not safe for use by multiple concurrent threads.  If a
  43  * SerialRef is to be used by more than one thread then access to the SerialRef
  44  * should be controlled by appropriate synchronization.
  45  *
  46  * @since 1.5
  47  */
  48 public class SerialRef implements Ref, Serializable, Cloneable {
  49 
  50     /**
  51      * String containing the base type name.
  52      * @serial
  53      */
  54     private String baseTypeName;
  55 
  56     /**
  57      * This will store the type <code>Ref</code> as an <code>Object</code>.
  58      */
  59     private Object object;
  60 
  61     /**
  62      * Private copy of the Ref reference.
  63      */
  64     private Ref reference;
  65 
  66     /**
  67      * Constructs a <code>SerialRef</code> object from the given <code>Ref</code>
  68      * object.
  69      *
  70      * @param ref a Ref object; cannot be <code>null</code>
  71      * @throws SQLException if a database access occurs; if <code>ref</code>
  72      *     is <code>null</code>; or if the <code>Ref</code> object returns a
  73      *     <code>null</code> value base type name.
  74      * @throws SerialException if an error occurs serializing the <code>Ref</code>
  75      *     object
  76      */
  77     public SerialRef(Ref ref) throws SerialException, SQLException {
  78         if (ref == null) {
  79             throw new SQLException("Cannot instantiate a SerialRef object " +
  80                 "with a null Ref object");
  81         }
  82         reference = ref;
  83         object = ref;
  84         if (ref.getBaseTypeName() == null) {
  85             throw new SQLException("Cannot instantiate a SerialRef object " +
  86                 "that returns a null base type name");
  87         } else {
  88             baseTypeName = ref.getBaseTypeName();
  89         }
  90     }
  91 
  92     /**
  93      * Returns a string describing the base type name of the <code>Ref</code>.
  94      *
  95      * @return a string of the base type name of the Ref
  96      * @throws SerialException in no Ref object has been set
  97      */
  98     public String getBaseTypeName() throws SerialException {
  99         return baseTypeName;
 100     }
 101 
 102     /**
 103      * Returns an <code>Object</code> representing the SQL structured type
 104      * to which this <code>SerialRef</code> object refers.  The attributes
 105      * of the structured type are mapped according to the given type map.
 106      *
 107      * @param map a <code>java.util.Map</code> object containing zero or
 108      *        more entries, with each entry consisting of 1) a <code>String</code>
 109      *        giving the fully qualified name of a UDT and 2) the
 110      *        <code>Class</code> object for the <code>SQLData</code> implementation
 111      *        that defines how the UDT is to be mapped
 112      * @return an object instance resolved from the Ref reference and mapped
 113      *        according to the supplied type map
 114      * @throws SerialException if an error is encountered in the reference
 115      *        resolution
 116      */
 117     public Object getObject(java.util.Map<String,Class<?>> map)
 118         throws SerialException
 119     {
 120         map = new Hashtable<String, Class<?>>(map);
 121         if (object != null) {
 122             return map.get(object);
 123         } else {
 124             throw new SerialException("The object is not set");
 125         }
 126     }
 127 
 128     /**
 129      * Returns an <code>Object</code> representing the SQL structured type
 130      * to which this <code>SerialRef</code> object refers.
 131      *
 132      * @return an object instance resolved from the Ref reference
 133      * @throws SerialException if an error is encountered in the reference
 134      *         resolution
 135      */
 136     public Object getObject() throws SerialException {
 137 
 138         if (reference != null) {
 139             try {
 140                 return reference.getObject();
 141             } catch (SQLException e) {
 142                 throw new SerialException("SQLException: " + e.getMessage());
 143             }
 144         }
 145 
 146         if (object != null) {
 147             return object;
 148         }
 149 
 150 
 151         throw new SerialException("The object is not set");
 152 
 153     }
 154 
 155     /**
 156      * Sets the SQL structured type that this <code>SerialRef</code> object
 157      * references to the given <code>Object</code> object.
 158      *
 159      * @param obj an <code>Object</code> representing the SQL structured type
 160      *        to be referenced
 161      * @throws SerialException if an error is encountered generating the
 162      * the structured type referenced by this <code>SerialRef</code> object
 163      */
 164     public void setObject(Object obj) throws SerialException {
 165         try {
 166             reference.setObject(obj);
 167         } catch (SQLException e) {
 168             throw new SerialException("SQLException: " + e.getMessage());
 169         }
 170         object = obj;
 171     }
 172 
 173     /**
 174      * Compares this SerialRef to the specified object.  The result is {@code
 175      * true} if and only if the argument is not {@code null} and is a {@code
 176      * SerialRef} object that represents the same object as this
 177      * object.
 178      *
 179      * @param  obj The object to compare this {@code SerialRef} against
 180      *
 181      * @return  {@code true} if the given object represents a {@code SerialRef}
 182      *          equivalent to this SerialRef, {@code false} otherwise
 183      *
 184      */
 185     public boolean equals(Object obj) {
 186         if (this == obj) {
 187             return true;
 188         }
 189         if(obj instanceof SerialRef) {
 190             SerialRef ref = (SerialRef)obj;
 191             return baseTypeName.equals(ref.baseTypeName) &&
 192                     object.equals(ref.object);
 193         }
 194         return false;
 195     }
 196 
 197     /**
 198      * Returns a hash code for this {@code SerialRef}.
 199      * @return  a hash code value for this object.
 200      */
 201     public int hashCode() {
 202         return (31 + object.hashCode()) * 31 + baseTypeName.hashCode();
 203     }
 204 
 205     /**
 206      * Returns a clone of this {@code SerialRef}.
 207      * The underlying {@code Ref} object will be set to null.
 208      *
 209      * @return  a clone of this SerialRef
 210      */
 211     public Object clone() {
 212         try {
 213             SerialRef ref = (SerialRef) super.clone();
 214             ref.reference = null;
 215             return ref;
 216         } catch (CloneNotSupportedException ex) {
 217             // this shouldn't happen, since we are Cloneable
 218             throw new InternalError();
 219         }
 220 
 221     }
 222 
 223     /**
 224      * readObject is called to restore the state of the SerialRef from
 225      * a stream.
 226      */
 227     private void readObject(ObjectInputStream s)
 228             throws IOException, ClassNotFoundException {
 229         ObjectInputStream.GetField fields = s.readFields();
 230         object = fields.get("object", null);
 231         baseTypeName = (String) fields.get("baseTypeName", null);
 232         reference = (Ref) fields.get("reference", null);
 233     }
 234 
 235     /**
 236      * writeObject is called to save the state of the SerialRef
 237      * to a stream.
 238      */
 239     private void writeObject(ObjectOutputStream s)
 240             throws IOException, ClassNotFoundException {
 241 
 242         ObjectOutputStream.PutField fields = s.putFields();
 243         fields.put("baseTypeName", baseTypeName);
 244         fields.put("object", object);
 245         // Note: this check to see if it is an instance of Serializable
 246         // is for backwards compatibility
 247         fields.put("reference", reference instanceof Serializable ? reference : null);
 248         s.writeFields();
 249     }
 250 
 251     /**
 252      * The identifier that assists in the serialization of this <code>SerialRef</code>
 253      * object.
 254      */
 255     static final long serialVersionUID = -4727123500609662274L;
 256 
 257 
 258 }
--- EOF ---