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  ;
40  import java.io.IOException  ;
41  import java.io.ObjectInput  ;
42  import java.io.ObjectOutput  ;
43  import java.io.Serializable  ;
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   implements Serializable  , Cloneable  , Comparable  , Externalizable   {
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   uuid)
129     throws NumberFormatException   {
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   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   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   ethernetAddress) throws CmsInitException {
216 
217         try {
218             m_ethernetAddress = new EthernetAddress(ethernetAddress);
219         } catch (Exception   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   uuid) {
235 
236         try {
237             return (null != uuid) && (null != UUID.valueOf(uuid));
238         } catch (NumberFormatException   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   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   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   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   in) throws IOException  , ClassNotFoundException   {
309 
310         Object   o = null;
311 
312         try {
313 
314             o = in.readObject();
315 
316         } catch (Exception   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  )in.readObject());
322             } else {
323                 throw new IOException  ("Cannot read externalized UUID because of a version mismatch.");
324             }
325         }
326 
327         if (o != null) {
328 
329             if (o instanceof String  ) {
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  )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  ("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   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   out) throws IOException   {
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 }
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags