KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > opencms > util > CmsUUID


1 /*
2  * File : $Source: /usr/local/cvs/opencms/src/org/opencms/util/CmsUUID.java,v $
3  * Date : $Date: 2006/04/28 15:20:52 $
4  * Version: $Revision: 1.21 $
5  *
6  * This library is part of OpenCms -
7  * the Open Source Content Mananagement System
8  *
9  * Copyright (c) 2005 Alkacon Software GmbH (http://www.alkacon.com)
10  *
11  * This library is free software; you can redistribute it and/or
12  * modify it under the terms of the GNU Lesser General Public
13  * License as published by the Free Software Foundation; either
14  * version 2.1 of the License, or (at your option) any later version.
15  *
16  * This library is distributed in the hope that it will be useful,
17  * but WITHOUT ANY WARRANTY; without even the implied warranty of
18  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
19  * Lesser General Public License for more details.
20  *
21  * For further information about Alkacon Software GmbH, please see the
22  * company website: http://www.alkacon.com
23  *
24  * For further information about OpenCms, please see the
25  * project website: http://www.opencms.org
26  *
27  * You should have received a copy of the GNU Lesser General Public
28  * License along with this library; if not, write to the Free Software
29  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
30  */

31
32 package org.opencms.util;
33
34 import org.opencms.main.CmsIllegalArgumentException;
35 import org.opencms.main.CmsInitException;
36 import org.opencms.main.CmsLog;
37 import org.opencms.main.CmsRuntimeException;
38
39 import java.io.Externalizable JavaDoc;
40 import java.io.IOException JavaDoc;
41 import java.io.ObjectInput JavaDoc;
42 import java.io.ObjectOutput JavaDoc;
43 import java.io.Serializable JavaDoc;
44
45 import org.apache.commons.logging.Log;
46
47 import org.doomdark.uuid.EthernetAddress;
48 import org.doomdark.uuid.UUID;
49 import org.doomdark.uuid.UUIDGenerator;
50
51 /**
52  * Generates a UUID using spatial and temporal uniqueness.<p>
53  *
54  * Spatial uniqueness is derived from
55  * ethernet address (MAC, 802.1); temporal from system clock.<p>
56  *
57  * For more information about the algorithm used, please see
58  * <a HREF="http://www.opengroup.org/dce/info/draft-leach-uuids-guids-01.txt">
59  * draft-leach-uuids-guids-01.txt</a>.<p>
60  *
61  * Because Java is unable to read the MAC address of the machine
62  * (without using JNI), the MAC address has to be provided first
63  * by using the static {@link #init(String)} method.<p>
64  *
65  * This class is just a facade wrapper for the "real" UUID implementation.<p>
66  *
67  * @author Alexander Kandzior
68  *
69  * @version $Revision: 1.21 $
70  *
71  * @since 6.0.0
72  */

73 public final class CmsUUID extends Object JavaDoc implements Serializable JavaDoc, Cloneable JavaDoc, Comparable JavaDoc, Externalizable JavaDoc {
74
75     /** The log object for this class. */
76     private static final Log LOG = CmsLog.getLog(CmsUUID.class);
77
78     /** Ethernet addess of the server machine. */
79     private static EthernetAddress m_ethernetAddress;
80
81     /** Flag to indicate if the ethernet address has been initialized. */
82     private static boolean m_isNotInitialized = true;
83
84     /** OpenCms UUID (name based uuid of "www.opencms.org" in the dns name space). */
85     private static UUID m_opencmsUUID = UUIDGenerator.getInstance().generateNameBasedUUID(
86         new UUID(UUID.NAMESPACE_DNS),
87         "www.opencms.org");
88
89     /** Constant for the null UUID. */
90     private static final CmsUUID NULL_UUID = new CmsUUID(UUID.getNullUUID());
91
92     /** Serial version UID required for safe serialization. */
93     private static final long serialVersionUID = 1736324454709298676L;
94
95     /** Internal UUID implementation. */
96     private UUID m_uuid;
97
98     /**
99      * Creates a new UUID.<p>
100      *
101      * Please note that the static init() method has to be called first to initialize the
102      * enternet address of the machine.<p>
103      */

104     public CmsUUID() {
105
106         if (m_isNotInitialized) {
107             throw new CmsRuntimeException(Messages.get().container(Messages.ERR_INVALID_ETHERNET_ADDRESS_0));
108         }
109         m_uuid = UUIDGenerator.getInstance().generateTimeBasedUUID(m_ethernetAddress);
110     }
111
112     /**
113      * Create a UUID based on a binary data array.<p>
114      *
115      * @param data a binary data array representing a UUID
116      */

117     public CmsUUID(byte[] data) {
118
119         m_uuid = new UUID(data);
120     }
121
122     /**
123      * Create a UUID based on a String.<p>
124      *
125      * @param uuid a String representing a UUID
126      * @throws NumberFormatException in case uuid is not a valid UUID
127      */

128     public CmsUUID(String JavaDoc uuid)
129     throws NumberFormatException JavaDoc {
130
131         m_uuid = new UUID(uuid);
132     }
133
134     /**
135      * Create a new UUID based on another one (used internal for cloning).<p>
136      *
137      * @param uuid the UUID to clone
138      */

139     private CmsUUID(UUID uuid) {
140
141         m_uuid = uuid;
142     }
143
144     /**
145      * Check that the given id is not the null id.<p>
146      *
147      * @param id the id to check
148      * @param canBeNull only if flag is set, <code>null</code> is accepted
149      *
150      * @see #isNullUUID()
151      */

152     public static void checkId(CmsUUID id, boolean canBeNull) {
153
154         if (canBeNull && id == null) {
155             return;
156         }
157         if ((!canBeNull && id == null) || id.isNullUUID()) {
158             throw new CmsIllegalArgumentException(Messages.get().container(Messages.ERR_INVALID_UUID_1, id));
159         }
160     }
161
162     /**
163      * Returns a constant (name based) UUID,
164      * based on the given name in the OpenCms name space.
165      *
166      * @param name the name to derive the uuid from
167      * @return name based UUID of the given name
168      */

169     public static CmsUUID getConstantUUID(String JavaDoc name) {
170
171         return new CmsUUID(UUIDGenerator.getInstance().generateNameBasedUUID(m_opencmsUUID, name));
172     }
173
174     /**
175      * Returns a String representing a dummy (random based) ethernet address.<p>
176      *
177      * @return a String representing a dummy (random based) ethernet address
178      */

179     public static String JavaDoc getDummyEthernetAddress() {
180
181         return UUIDGenerator.getInstance().getDummyAddress().toString();
182     }
183
184     /**
185      * Returns a null UUID,
186      * use this null UUID to check if a UUID has been initilized or not.<p>
187      *
188      * @return a null UUID
189      */

190     public static CmsUUID getNullUUID() {
191
192         return NULL_UUID;
193     }
194
195     /**
196      * Returns a constant (name based) UUID for OpenCms,
197      * based on "www.opencms.org" in the dns name space.
198      *
199      * @return name based UUID of OpenCms
200      */

201     public static CmsUUID getOpenCmsUUID() {
202
203         return new CmsUUID(m_opencmsUUID);
204     }
205
206     /**
207      * Initialize the UUID generator with the ethernet address of the server machine.<p>
208      *
209      * The ethernetAddress parameter must represent a 'standard' ethernet MAC address string
210      * (e.g. '00:C0:F0:3D:5B:7C').
211      *
212      * @param ethernetAddress the ethernet address of the server machine
213      * @throws CmsInitException in case the ethernetAddress String is not a valid ethernet address
214      */

215     public static void init(String JavaDoc ethernetAddress) throws CmsInitException {
216
217         try {
218             m_ethernetAddress = new EthernetAddress(ethernetAddress);
219         } catch (Exception JavaDoc e) {
220             throw new CmsInitException(Messages.get().container(
221                 Messages.ERR_INVALID_ETHERNET_ADDRESS_1,
222                 ethernetAddress));
223         }
224         m_isNotInitialized = false;
225     }
226
227     /**
228      * Returns <code>true</code> if the given UUID is valid.<p>
229      *
230      * @param uuid the UUID to check
231      *
232      * @return <code>true</code> if the given UUID is valid
233      */

234     public static boolean isValidUUID(String JavaDoc uuid) {
235
236         try {
237             return (null != uuid) && (null != UUID.valueOf(uuid));
238         } catch (NumberFormatException JavaDoc e) {
239             // return false
240
}
241         return false;
242     }
243
244     /**
245      * Creates a clone of this CmsUUID.<p>
246      *
247      * @return a clone of this CmsUUID
248      */

249     public Object JavaDoc clone() {
250
251         if (this == NULL_UUID) {
252             return NULL_UUID;
253         }
254         return new CmsUUID((UUID)m_uuid.clone());
255     }
256
257     /**
258      * @see java.lang.Comparable#compareTo(java.lang.Object)
259      */

260     public int compareTo(Object JavaDoc obj) {
261
262         if (obj instanceof CmsUUID) {
263             return m_uuid.compareTo(((CmsUUID)obj).m_uuid);
264         }
265         return 0;
266     }
267
268     /**
269      * @see java.lang.Object#equals(java.lang.Object)
270      */

271     public boolean equals(Object JavaDoc obj) {
272
273         if (obj == this) {
274             return true;
275         }
276         if (obj instanceof CmsUUID) {
277             return ((CmsUUID)obj).m_uuid.equals(m_uuid);
278         }
279         return false;
280     }
281
282     /**
283      * Optimized hashCode implementation for UUID's.<p>
284      *
285      * @see java.lang.Object#hashCode()
286      */

287     public int hashCode() {
288
289         return m_uuid.hashCode();
290     }
291
292     /**
293      * Returns true if this UUID is equal to the null UUID.<p>
294      *
295      * @return true if this UUID is equal to the null UUID
296      */

297     public boolean isNullUUID() {
298
299         if (this == NULL_UUID) {
300             return true;
301         }
302         return m_uuid.equals(UUID.getNullUUID());
303     }
304
305     /**
306      * @see java.io.Externalizable#readExternal(java.io.ObjectInput)
307      */

308     public void readExternal(ObjectInput JavaDoc in) throws IOException JavaDoc, ClassNotFoundException JavaDoc {
309
310         Object JavaDoc o = null;
311
312         try {
313
314             o = in.readObject();
315
316         } catch (Exception JavaDoc e) {
317             // there was an error getting the object form the ObjectInput
318
// so try to access it in the old way as it was done before
319
// OpenCms 6.2
320
if (in.readLong() == serialVersionUID) {
321                 m_uuid = new UUID((String JavaDoc)in.readObject());
322             } else {
323                 throw new IOException JavaDoc("Cannot read externalized UUID because of a version mismatch.");
324             }
325         }
326
327         if (o != null) {
328
329             if (o instanceof String JavaDoc) {
330                 // this UUID has been serialized using the new method
331
if (LOG.isDebugEnabled()) {
332                     LOG.debug(Messages.get().getBundle().key(Messages.LOG_READ_UUID_1, o));
333                 }
334                 m_uuid = new UUID((String JavaDoc)o);
335             } else if (o instanceof UUID) {
336                 // this UUID has been serialized using the old method
337
if (LOG.isDebugEnabled()) {
338                     LOG.debug(Messages.get().getBundle().key(Messages.LOG_READ_UUID_OLD_1, o));
339                 }
340                 m_uuid = (UUID)o;
341             }
342         }
343
344         // throw an error if the uuid could ne be deserialized
345
if (m_uuid == null) {
346             // UUID cannot be deserialized
347
if (LOG.isDebugEnabled()) {
348                 LOG.debug(Messages.get().getBundle().key(Messages.LOG_ERR_READ_UUID_0));
349             }
350             throw new IOException JavaDoc("Cannot read externalized UUID.");
351         }
352
353     }
354
355     /**
356      * Returns the UUID as a 16-byte byte array.<p>
357      *
358      * @return 16-byte byte array that contains the UUID's bytes in the network byte order
359      */

360     public byte[] toByteArray() {
361
362         return m_uuid.toByteArray();
363     }
364
365     /**
366      * @see java.lang.Object#toString()
367      */

368     public String JavaDoc toString() {
369
370         return m_uuid.toString();
371     }
372
373     /**
374      *
375      * @see java.io.Externalizable#writeExternal(java.io.ObjectOutput)
376      */

377     public void writeExternal(ObjectOutput JavaDoc out) throws IOException JavaDoc {
378
379         if (LOG.isDebugEnabled()) {
380             LOG.debug(Messages.get().getBundle().key(Messages.LOG_WRITE_UUID_1, m_uuid.toString()));
381         }
382         out.writeObject(m_uuid.toString());
383     }
384 }
Popular Tags