RowId


1   /*
2    * @(#)RowId.java   1.5 06/05/28
3    *
4    * Copyright 2006 Sun Microsystems, Inc. All rights reserved.
5    * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6    */
7   
8   package java.sql;
9    
10  /**
11   * 
12   * The representation (mapping) in the Java programming language of an SQL ROWID
13   * value. An SQL ROWID is a built-in type, a value of which can be thought of as
14   * an address  for its identified row in a database table. Whether that address
15   * is logical or, in any  respects, physical is determined by its originating data 
16   * source.  
17   * <p>
18   * Methods in the interfaces <code>ResultSet</code>, <code>CallableStatement</code>,
19   * and <code>PreparedStatement</code>, such as <code>getRowId</code> and <code>setRowId</code>
20   * allow a programmer to access a SQL <code>ROWID</code>  value. The <code>RowId</code>
21   * interface provides a method 
22   * for representing the value of the <code>ROWID</code> as a byte array or as a 
23   * <code>String</code>. 
24   * <p>
25   * The method <code>getRowIdLifetime</code> in the interface <code>DatabaseMetaData</code>,
26   * can be used 
27   * to determine if a <code>RowId</code> object remains valid for the duration of the transaction in 
28   * which  the <code>RowId</code> was created, the duration of the session in which 
29   * the <code>RowId</code> was created,
30   * or, effectively, for as long as its identified row is not deleted. In addition
31   * to specifying the duration of its valid lifetime outside its originating data
32   * source, <code>getRowIdLifetime</code> specifies the duration of a <code>ROWID</code>
33   * value's valid lifetime 
34   * within its originating data source. In this, it differs from a large object,
35   * because there is no limit on the valid lifetime of a large  object within its 
36   * originating data source.  
37   * <p>
38   * All methods on the <code>RowId</code> interface must be fully implemented if the 
39   * JDBC driver supports the data type.
40   *
41   * @see java.sql.DatabaseMetaData
42   * @since 1.6
43   */
44  
45  public interface RowId {
46      /**
47       * Compares this <code>RowId</code> to the specified object. The result is 
48       * <code>true</code> if and only if the argument is not null and is a RowId 
49       * object that represents the same ROWID as  this object. 
50       * <p>
51       * It is important 
52       * to consider both the origin and the valid lifetime of a <code>RowId</code>
53       * when comparing it to another <code>RowId</code>. If both are valid, and 
54       * both are from the same table on the same data source, then if they are equal
55       * they identify 
56       * the same row; if one or more is no longer guaranteed to be valid, or if 
57       * they originate from different data sources, or different tables on the
58       * same data source, they  may be equal but still
59       * not identify the same row. 
60       * 
61       * @param obj the <code>Object</code> to compare this <code>RowId</code> object
62       *     against.
63       * @return true if the <code>RowId</code>s are equal; false otherwise
64       * @since 1.6
65       */
66      boolean equals(Object   obj);
67      
68      /** 
69       * Returns an array of bytes representing the value of the SQL <code>ROWID</code>
70       * designated by this <code>java.sql.RowId</code> object.
71       * 
72       * @return an array of bytes, whose length is determined by the driver supplying
73       *     the connection, representing the value of the ROWID designated by this
74       *     java.sql.RowId object.  
75       */
76       byte[] getBytes();
77       
78       /**
79        * Returns a String representing the value of the SQL ROWID designated by this
80        * <code>java.sql.RowId</code> object.
81        * <p>
82        *Like <code>java.sql.Date.toString()</code>
83        * returns the contents of its DATE as the <code>String</code> "2004-03-17" 
84        * rather than as  DATE literal in SQL (which would have been the <code>String</code>
85        * DATE "2004-03-17"), toString() 
86        * returns the contents of its ROWID in a form specific to the driver supplying 
87        * the connection, and possibly not as a <code>ROWID</code> literal. 
88        * 
89        * @return a String whose format is determined by the driver supplying the 
90        *     connection, representing the value of the <code>ROWID</code> designated
91        *     by this <code>java.sql.RowId</code>  object. 
92        */
93       String   toString();
94       
95       /**
96        * Returns a hash code value of this <code>RowId</code> object.
97        *
98        * @return a hash code for the <code>RowId</code>
99        */
100      int hashCode();
101 
102 }
103 
104 
105
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags