KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > com > triactive > jdo > store > OID


1 /*
2  * Copyright 2002 (C) TJDO.
3  * All rights reserved.
4  *
5  * This software is distributed under the terms of the TJDO License version 1.0.
6  * See the terms of the TJDO License in the documentation provided with this software.
7  *
8  * $Id: OID.java,v 1.4 2004/01/25 22:31:26 jackknifebarber Exp $
9  */
10
11 package com.triactive.jdo.store;
12
13
14 /**
15  * An object identifier. OIDs are normally used as object identifiers for
16  * persistent objects that use data store identity. They're also used for
17  * view objects, which actually use non-data store identity.
18  *
19  * <p>An OID is effectively a long containing a value in the range 0 to
20  * 2<sup>60</sup>-1. The 60 bits encode three unsigned integer ID values; a
21  * 15-bit class ID value, a 30-bit object ID <i>high value</i>, and a 15-bit
22  * object ID <i>low value</i>.
23  *
24  * <p>The object ID value is separated into two parts to facilitate the use of a
25  * particular strategy for efficiently generating unique OID values, called the
26  * <dfn>high/low approach</dfn>. In this approach, the high value is obtained
27  * from a persistent store, and the low value is assigned locally by the
28  * application. The advantage is performance; it avoids the bottleneck of
29  * hitting the persistent store every time an ID needs to be generated.
30  *
31  * @author <a HREF="mailto:mmartin5@austin.rr.com">Mike Martin</a>
32  * @version $Revision: 1.4 $
33  *
34  * @see StoreManager
35  */
36
37 public final class OID implements java.io.Serializable JavaDoc
38 {
39     /**
40      * The maximum value of an OID as a <tt>long</tt>. This equals
41      * 2<sup>60</sup> - 1.
42      */
43     public static final long MAX_VALUE = 0xfffffffffffffffL;
44
45     /**
46      * The maximum class ID value. This equals 2<sup>15</sup> - 1.
47      */
48     public static final int MAX_CLASSID = 0x7fff;
49
50     /**
51      * The maximum hi portion of an object ID value. This equals
52      * 2<sup>30</sup> - 1.
53      */
54     public static final int MAX_OBJIDHI = 0x3fffffff;
55
56     /**
57      * The maximum lo portion of an object ID value. This equals
58      * 2<sup>15</sup> - 1.
59      */
60     public static final int MAX_OBJIDLO = 0x7fff;
61
62     /**
63      * The maximum length of an OID in string form.
64      */
65     public static final int MAX_LENGTH = 14;
66
67
68     /**
69      * The OID value as a long.
70      */
71     private long value;
72
73
74     /**
75      * Constructs an OID from its long value.
76      *
77      * @param value the long value of the OID.
78      *
79      * @exception IllegalArgumentException
80      * if the argument is not in the range 0 to {@link #MAX_VALUE}.
81      */
82
83     public OID(long value) throws IllegalArgumentException JavaDoc
84     {
85         if (value < 0 || value > MAX_VALUE)
86             throw new IllegalArgumentException JavaDoc("Invalid OID value: " + value);
87
88         this.value = value;
89     }
90
91
92     /**
93      * Constructs an OID from three integer values. All three arguments must be
94      * between zero and their respective maximums {@link #MAX_CLASSID},
95      * {@link #MAX_OBJIDHI}, and {@link #MAX_OBJIDLO}.
96      *
97      * @param classID the class ID value.
98      * @param objIDHi the hi portion of the object ID value.
99      * @param objIDLo the lo portion of the object ID value.
100      *
101      * @exception IllegalArgumentException
102      * if one of the arguments is out of range.
103      */
104
105     public OID(int classID, int objIDHi, int objIDLo) throws IllegalArgumentException JavaDoc
106     {
107         if (classID < 0 || classID > MAX_CLASSID)
108             throw new IllegalArgumentException JavaDoc("Invalid class ID value: " + classID);
109
110         if (objIDHi < 0 || objIDHi > MAX_OBJIDHI)
111             throw new IllegalArgumentException JavaDoc("Invalid object ID hi value: " + objIDHi);
112
113         if (objIDLo < 0 || objIDLo > MAX_OBJIDLO)
114             throw new IllegalArgumentException JavaDoc("Invalid object ID lo value: " + objIDLo);
115
116         value = ((long)classID << 45) | ((long)objIDHi << 15) | objIDLo;
117     }
118
119
120     /**
121      * Constructs an OID from its string representation.
122      *
123      * @param s the string representation of an OID.
124      *
125      * @exception IllegalArgumentException
126      * if the given string representation is not valid.
127      *
128      * @see #toString
129      */
130
131     public OID(String JavaDoc s) throws IllegalArgumentException JavaDoc
132     {
133         if (s.length() != 14 || s.charAt(3) != '-' || s.charAt(10) != '-')
134             throw new IllegalArgumentException JavaDoc("Invalid OID string value: " + s);
135
136         StringBuffer JavaDoc buf = new StringBuffer JavaDoc(s);
137
138         buf.deleteCharAt(10).deleteCharAt(3);
139
140         value = Long.parseLong(buf.toString(), 32);
141
142         if (value < 0 || value > MAX_VALUE)
143             throw new IllegalArgumentException JavaDoc("Invalid OID string value: " + s);
144     }
145
146
147     /**
148      * Returns the class ID portion of the OID.
149      *
150      * @return the class ID.
151      */
152
153     public int getClassID()
154     {
155         return (int)(value >> 45);
156     }
157
158
159     /**
160      * Returns the value of this OID as a long value.
161      *
162      * @return the value of this OID as a <tt>long</tt>.
163      */
164
165     public long longValue()
166     {
167         return value;
168     }
169
170
171     public boolean equals(Object JavaDoc obj)
172     {
173         if (obj == this)
174             return true;
175
176         if (!(obj instanceof OID))
177             return false;
178
179         return (value == ((OID)obj).value);
180     }
181
182
183     public int hashCode()
184     {
185         return (int)(value ^ (value >> 32));
186     }
187
188
189     /**
190      * Returns the string representation of the OID. The string representation
191      * is all three of the component values in base 32, zero-filled, separated
192      * by a dash '-' character:
193      *
194      * <blockquote><pre>
195      * ccc-hhhhhh-lll
196      * </pre></blockquote>
197      *
198      * @return the string representation of the OID.
199      */
200
201     public String JavaDoc toString()
202     {
203         StringBuffer JavaDoc s = new StringBuffer JavaDoc("00000000000").append(Long.toString(value, 32));
204
205         s.delete(0, s.length() - 12).insert(3, '-').insert(10, '-');
206
207         return s.toString();
208     }
209 }
210
Popular Tags