001: /*
002: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
003: *
004: * Copyright 1997-2007 Sun Microsystems, Inc. All rights reserved.
005: *
006: * The contents of this file are subject to the terms of either the GNU
007: * General Public License Version 2 only ("GPL") or the Common
008: * Development and Distribution License("CDDL") (collectively, the
009: * "License"). You may not use this file except in compliance with the
010: * License. You can obtain a copy of the License at
011: * http://www.netbeans.org/cddl-gplv2.html
012: * or nbbuild/licenses/CDDL-GPL-2-CP. See the License for the
013: * specific language governing permissions and limitations under the
014: * License. When distributing the software, include this License Header
015: * Notice in each file and include the License file at
016: * nbbuild/licenses/CDDL-GPL-2-CP. Sun designates this
017: * particular file as subject to the "Classpath" exception as provided
018: * by Sun in the GPL Version 2 section of the License file that
019: * accompanied this code. If applicable, add the following below the
020: * License Header, with the fields enclosed by brackets [] replaced by
021: * your own identifying information:
022: * "Portions Copyrighted [year] [name of copyright owner]"
023: *
024: * Contributor(s):
025: *
026: * The Original Software is NetBeans. The Initial Developer of the Original
027: * Software is Sun Microsystems, Inc. Portions Copyright 1997-2007 Sun
028: * Microsystems, Inc. All Rights Reserved.
029: *
030: * If you wish your version of this file to be governed by only the CDDL
031: * or only the GPL Version 2, indicate your decision by adding
032: * "[Contributor] elects to include this software in this distribution
033: * under the [CDDL or GPL Version 2] license." If you do not indicate a
034: * single choice of license, a recipient has the option to distribute
035: * your version of this file under either the CDDL, the GPL Version 2 or
036: * to extend the choice of license to its licensees as provided above.
037: * However, if you add GPL Version 2 code and therefore, elected the GPL
038: * Version 2 license, then the option applies only if the new code is
039: * made subject to such option by the copyright holder.
040: */
041:
042: package com.sun.data.provider;
043:
044: import java.io.Serializable;
045:
046: /**
047: * <p>RowKey is a representation of an identifier for a specific data row that
048: * may be retrieved from a {@link TableDataProvider}. Specialized
049: * implementations might also provide extra capabilities for navigation
050: * between rows, or other value added services.</p>
051: *
052: * <p>A RowKey (and rowId) is expected to remain valid for as long as possible -
053: * meaning when a RowKey is fetched from a TableDataProvider, it is considered
054: * an address of a particular row in that TableDataProvider. If rows have been
055: * added or removed from the TableDataProvider, a previously fetched RowKey
056: * should still represent the row it did when it was first retrieved. A common
057: * strategy for TableDataProvider implementations is to store intrinsicly
058: * "primary key-like" data from the underlying data source inside of a
059: * specialized RowKey implementation. Another strategy is to store a random
060: * hash index in the RowKeys, and maintain a map inside the TableDataProvider
061: * implementation to resolve the RowKeys back to the underlying data rows. This
062: * insolates consumers of the TableDataProvider implementation from row index
063: * changes (due to inserts, deletes, etc) in the underlying data source.</p>
064: *
065: * <p>At any point a user might call {@link TableDataProvider#getRowKey(String)}
066: * in order to fetch a valid RowKey for a particular rowId, so the
067: * TableDataProvider must be capable of resolving a rowId back to a unique
068: * RowKey.</p>
069: *
070: * <p>RowKey implements Comparable so that batched deletes and inserts can be
071: * done in reverse order to help ensure consistency of row order. This is only
072: * for blind operations implemented where there is no knowledge of a specific
073: * RowKey or TableDataProvider implementations. A RowKey implementation might
074: * not support intrinsic ordering of any type.</p>
075: *
076: * @author Joe Nuxoll
077: */
078: public class RowKey implements Serializable, Comparable {
079:
080: /**
081: * A convenient static empty array to use for no-op method returns
082: */
083: public static final RowKey[] EMPTY_ARRAY = new RowKey[0];
084:
085: /**
086: * Constructs an uninitialized RowKey.
087: */
088: public RowKey() {
089: }
090:
091: /**
092: * Constructs a new RowKey with the specified canonical ID.
093: *
094: * @param rowId The desired canonical ID String
095: */
096: public RowKey(String rowId) {
097: this .rowId = rowId;
098: }
099:
100: /**
101: * @param rowId the canonical internal identifier of this {@link RowKey}
102: */
103: public void setRowId(String rowId) {
104: this .rowId = rowId;
105: }
106:
107: /**
108: * @return the canonical internal identifier of this {@link RowKey}
109: */
110: public String getRowId() {
111: return rowId;
112: }
113:
114: /**
115: * Standard equals implementation. This method compares the RowKey id
116: * values for equality.
117: *
118: * @param o the Object to check equality
119: * @return true if equal, false if not
120: * @see Object#equals(Object)
121: */
122: public boolean equals(Object o) {
123: if (o instanceof RowKey) {
124: String rkRowId = ((RowKey) o).getRowId();
125: String this RowId = getRowId();
126: return this RowId == rkRowId
127: || (this RowId != null && this RowId.equals(rkRowId));
128: }
129: return false;
130: }
131:
132: /**
133: * @return the hashCode of a blank String if the RowKey id is null, or the
134: * hashCode of the RowKey id otherwise.
135: * @see Object#hashCode()
136: */
137: public int hashCode() {
138: String this RowId = getRowId();
139: if (this RowId == null) {
140: return "".hashCode();
141: }
142: return this RowId.hashCode();
143: }
144:
145: /**
146: * <p>Standard implementation of compareTo(Object). This checks for
147: * equality first (using equals(Object)), then compares the rowId strings.
148: * This should be overridden by RowKey implementations that have a notion of
149: * order. This allows for deletions and insertions to be done in reverse
150: * order to help ensure the longevity of valid RowKeys.</p>
151: *
152: * {@inheritDoc}
153: */
154: public int compareTo(Object o) {
155: if (this .equals(o)) {
156: return 0;
157: }
158: RowKey rk = (RowKey) o;
159: String this RowId = getRowId();
160: if (this RowId == null) {
161: this RowId = "";
162: }
163: return this RowId.compareTo(rk.getRowId());
164: }
165:
166: private String rowId;
167:
168: public String toString() {
169: return "RowKey[" + getRowId() + "]"; // NOI18N
170: }
171: }
|