/*
* This library is part of OpenCms -
* the Open Source Content Management System
*
* Copyright (c) Alkacon Software GmbH (http://www.alkacon.com)
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 2.1 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* For further information about Alkacon Software GmbH, please see the
* company website: http://www.alkacon.com
*
* For further information about OpenCms, please see the
* project website: http://www.opencms.org
*
* You should have received a copy of the GNU Lesser General Public
* License along with this library; if not, write to the Free Software
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
*/
package org.opencms.util.ant;
import java.io.Serializable;
import org.safehaus.uuid.EthernetAddress;
import org.safehaus.uuid.UUID;
import org.safehaus.uuid.UUIDGenerator;
/**
* Generates a UUID using spatial and temporal uniqueness.<p>
*
* Spatial uniqueness is derived from
* ethernet address (MAC, 802.1); temporal from system clock.<p>
*
* For more information about the algorithm used, please see
* <a href="http://www.opengroup.org/dce/info/draft-leach-uuids-guids-01.txt">
* draft-leach-uuids-guids-01.txt</a>.<p>
*
* Because Java is unable to read the MAC address of the machine
* (without using JNI), the MAC address has to be provided first
* by using the static {@link #init(String)} method.<p>
*
* This class is just a facade wrapper for the "real" UUID implementation.<p>
*
* @since 6.0.0
*/
public final class CmsUUID extends Object implements Serializable, Cloneable, Comparable<CmsUUID> {
/** Ethernet address of the server machine. */
private static EthernetAddress m_ethernetAddress;
/** OpenCms UUID (name based uuid of "www.opencms.org" in the dns name space). */
private static UUID m_opencmsUUID = UUIDGenerator.getInstance().generateNameBasedUUID(
new UUID(UUID.NAMESPACE_DNS),
"www.opencms.org");
/** Constant for the null UUID. */
private static final CmsUUID NULL_UUID = new CmsUUID(UUID.getNullUUID());
/** Serial version UID required for safe serialization. */
private static final long serialVersionUID = 1736324454709298676L;
/** Internal UUID implementation. */
private transient UUID m_uuid;
/**
* Creates a new UUID.<p>
*
* Please note that the static init() method has to be called first to initialize the
* internet address of the machine.<p>
*/
public CmsUUID() {
if (m_ethernetAddress == null) {
// if no ethernet address is available, generate a dummy
// this is required because otherwise we can't ever de-serialize a CmsUUID outside of OpenCms,
// since the empty constructor is called when the de-serialization takes place
init(getDummyEthernetAddress());
}
m_uuid = UUIDGenerator.getInstance().generateTimeBasedUUID(m_ethernetAddress);
}
/**
* Create a UUID based on a binary data array.<p>
*
* @param data a binary data array representing a UUID
*/
public CmsUUID(byte[] data) {
m_uuid = new UUID(data);
}
/**
* Create a UUID based on a String.<p>
*
* @param uuid a String representing a UUID
* @throws NumberFormatException in case uuid is not a valid UUID
*/
public CmsUUID(String uuid)
throws NumberFormatException {
m_uuid = new UUID(uuid);
}
/**
* Create a new UUID based on another one (used internal for cloning).<p>
*
* @param uuid the UUID to clone
*/
private CmsUUID(UUID uuid) {
m_uuid = uuid;
}
/**
* Check that the given id is not the null id.<p>
*
* @param id the id to check
* @param canBeNull only if flag is set, <code>null</code> is accepted
*
* @see #isNullUUID()
*/
public static void checkId(CmsUUID id, boolean canBeNull) {
if (canBeNull && (id == null)) {
return;
}
if ((!canBeNull && (id == null)) || id.isNullUUID()) {
throw new IllegalArgumentException("INVALID_UUID" + id);
}
}
/**
* Returns a constant (name based) UUID,
* based on the given name in the OpenCms name space.
*
* @param name the name to derive the uuid from
* @return name based UUID of the given name
*/
public static CmsUUID getConstantUUID(String name) {
return new CmsUUID(UUIDGenerator.getInstance().generateNameBasedUUID(m_opencmsUUID, name));
}
/**
* Returns a String representing a dummy (random based) ethernet address.<p>
*
* @return a String representing a dummy (random based) ethernet address
*/
public static String getDummyEthernetAddress() {
return UUIDGenerator.getInstance().getDummyAddress().toString();
}
/**
* Returns a null UUID,
* use this null UUID to check if a UUID has been initialized or not.<p>
*
* @return a null UUID
*/
public static CmsUUID getNullUUID() {
return NULL_UUID;
}
/**
* Returns a constant (name based) UUID for OpenCms,
* based on "www.opencms.org" in the dns name space.
*
* @return name based UUID of OpenCms
*/
public static CmsUUID getOpenCmsUUID() {
return new CmsUUID(m_opencmsUUID);
}
/**
* Initialize the UUID generator with the ethernet address of the server machine.<p>
*
* The ethernetAddress parameter must represent a 'standard' ethernet MAC address string
* (e.g. '00:C0:F0:3D:5B:7C').
*
* @param ethernetAddress the ethernet address of the server machine
*
* @throws IllegalStateException in case the ethernetAddress String is not a valid ethernet address
*/
public static void init(String ethernetAddress) throws IllegalStateException {
try {
m_ethernetAddress = new EthernetAddress(ethernetAddress);
} catch (Exception e) {
throw new IllegalStateException("INVALID_ETHERNET_ADDRESS" + ethernetAddress);
}
}
/**
* Returns <code>true</code> if the given UUID is valid.<p>
*
* @param uuid the UUID to check
*
* @return <code>true</code> if the given UUID is valid
*/
public static boolean isValidUUID(String uuid) {
try {
return (null != uuid) && (null != UUID.valueOf(uuid));
} catch (NumberFormatException e) {
// return false
}
return false;
}
/**
* Returns the given String transformed to a UUID in case the String is a valid UUID.<p>
*
* @param uuid the String to transform to a UUID
*
* @return the given String transformed to a UUID in case the String is a valid UUID
*
* @throws NumberFormatException in case the String is no valid UUID
*/
public static CmsUUID valueOf(String uuid) throws NumberFormatException {
return new CmsUUID(UUID.valueOf(uuid));
}
/**
* Creates a clone of this CmsUUID.<p>
*
* @return a clone of this CmsUUID
*/
@Override
public Object clone() {
if (this == NULL_UUID) {
return NULL_UUID;
}
return new CmsUUID((UUID)m_uuid.clone());
}
/**
* @see java.lang.Comparable#compareTo(Object)
*/
public int compareTo(CmsUUID obj) {
return m_uuid.compareTo(obj.m_uuid);
}
/**
* @see java.lang.Object#equals(java.lang.Object)
*/
@Override
public boolean equals(Object obj) {
if (obj == this) {
return true;
}
if (obj instanceof CmsUUID) {
return ((CmsUUID)obj).m_uuid.equals(m_uuid);
}
return false;
}
/**
* Returns the String representation of this UUID, same as {@link #toString()}.<p>
*
* This method is useful if bean like access to the UUID String is required.<p>
*
* @return the String representation of this UUID
*/
public String getStringValue() {
return toString();
}
/**
* Optimized hashCode implementation for UUID's.<p>
*
* @see java.lang.Object#hashCode()
*/
@Override
public int hashCode() {
return m_uuid.hashCode();
}
/**
* Returns true if this UUID is equal to the null UUID.<p>
*
* @return true if this UUID is equal to the null UUID
*/
public boolean isNullUUID() {
if (this == NULL_UUID) {
return true;
}
return m_uuid.equals(UUID.getNullUUID());
}
/**
* Returns the UUID as a 16-byte byte array.<p>
*
* @return 16-byte byte array that contains the UUID's bytes in the network byte order
*/
public byte[] toByteArray() {
return m_uuid.toByteArray();
}
/**
* @see java.lang.Object#toString()
*/
@Override
public String toString() {
return m_uuid.toString();
}
}