View Javadoc
1   /*
2    * Copyright (c) 2003, 2013, 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.net.URL;
31  
32  
33  /**
34   * A serialized mapping in the Java programming language of an SQL
35   * <code>DATALINK</code> value. A <code>DATALINK</code> value
36   * references a file outside of the underlying data source that the
37   * data source manages.
38   * <P>
39   * <code>RowSet</code> implementations can use the method <code>RowSet.getURL</code>
40   * to retrieve a <code>java.net.URL</code> object, which can be used
41   * to manipulate the external data.
42   * <pre>
43   *      java.net.URL url = rowset.getURL(1);
44   * </pre>
45   *
46   * <h3> Thread safety </h3>
47   *
48   * A SerialDatalink is not safe for use by multiple concurrent threads.  If a
49   * SerialDatalink is to be used by more than one thread then access to the
50   * SerialDatalink should be controlled by appropriate synchronization.
51   */
52  public class SerialDatalink implements Serializable, Cloneable {
53  
54      /**
55       * The extracted URL field retrieved from the DATALINK field.
56       * @serial
57       */
58      private URL url;
59  
60      /**
61       * The SQL type of the elements in this <code>SerialDatalink</code>
62       * object.  The type is expressed as one of the contants from the
63       * class <code>java.sql.Types</code>.
64       * @serial
65       */
66      private int baseType;
67  
68      /**
69       * The type name used by the DBMS for the elements in the SQL
70       * <code>DATALINK</code> value that this SerialDatalink object
71       * represents.
72       * @serial
73       */
74      private String baseTypeName;
75  
76      /**
77        * Constructs a new <code>SerialDatalink</code> object from the given
78        * <code>java.net.URL</code> object.
79        * <P>
80        * @param url the {@code URL} to create the {@code SerialDataLink} from
81        * @throws SerialException if url parameter is a null
82        */
83      public SerialDatalink(URL url) throws SerialException {
84          if (url == null) {
85              throw new SerialException("Cannot serialize empty URL instance");
86          }
87          this.url = url;
88      }
89  
90      /**
91       * Returns a new URL that is a copy of this <code>SerialDatalink</code>
92       * object.
93       *
94       * @return a copy of this <code>SerialDatalink</code> object as a
95       * <code>URL</code> object in the Java programming language.
96       * @throws SerialException if the <code>URL</code> object cannot be de-serialized
97       */
98      public URL getDatalink() throws SerialException {
99  
100         URL aURL = null;
101 
102         try {
103             aURL = new URL((this.url).toString());
104         } catch (java.net.MalformedURLException e) {
105             throw new SerialException("MalformedURLException: " + e.getMessage());
106         }
107         return aURL;
108     }
109 
110     /**
111      * Compares this {@code SerialDatalink} to the specified object.
112      * The result is {@code true} if and only if the argument is not
113      * {@code null} and is a {@code SerialDatalink} object whose URL is
114      * identical to this object's URL
115      *
116      * @param  obj The object to compare this {@code SerialDatalink} against
117      *
118      * @return  {@code true} if the given object represents a {@code SerialDatalink}
119      *          equivalent to this SerialDatalink, {@code false} otherwise
120      *
121      */
122     public boolean equals(Object obj) {
123         if (this == obj) {
124             return true;
125         }
126         if (obj instanceof SerialDatalink) {
127             SerialDatalink sdl = (SerialDatalink) obj;
128             return url.equals(sdl.url);
129         }
130         return false;
131     }
132 
133     /**
134      * Returns a hash code for this {@code SerialDatalink}. The hash code for a
135      * {@code SerialDatalink} object is taken as the hash code of
136      * the {@code URL} it stores
137      *
138      * @return  a hash code value for this object.
139      */
140     public int hashCode() {
141         return 31 + url.hashCode();
142     }
143 
144     /**
145      * Returns a clone of this {@code SerialDatalink}.
146      *
147      * @return  a clone of this SerialDatalink
148      */
149     public Object clone() {
150         try {
151             SerialDatalink sdl = (SerialDatalink) super.clone();
152             return sdl;
153         } catch (CloneNotSupportedException ex) {
154             // this shouldn't happen, since we are Cloneable
155             throw new InternalError();
156         }
157     }
158 
159     /**
160      * readObject and writeObject are called to restore the state
161      * of the {@code SerialDatalink}
162      * from a stream. Note: we leverage the default Serialized form
163      */
164 
165     /**
166      * The identifier that assists in the serialization of this
167      *  {@code SerialDatalink} object.
168      */
169     static final long serialVersionUID = 2826907821828733626L;
170 }