Split xp.contrib's "ietf"

[thekid]

Scope of Change

The UUID class will be merged into XP Framework core (as util.UUID) and the ietf package will be renamed to punycode.

Rationale

The "ietf" module contains both PunyCode and UUID implementations, which are completely unrelated.

Functionality

The new UUID class will offer a slightly different API than the current one.

Old API

public class org.ietf.UUID extends lang.Object {
  public org.ietf.UUID::$time_low
  public org.ietf.UUID::$time_mid
  public org.ietf.UUID::$time_hi_and_version
  public org.ietf.UUID::$clock_seq_low
  public org.ietf.UUID::$clock_seq_hi_and_reserved
  public org.ietf.UUID::$node

  public static org.ietf.UUID create()
  public static org.ietf.UUID fromString(string $str) throws lang.FormatException

  public string toString()
  public string hashCode()
  public bool equals(var $cmp)
  public string getClassName()
  public lang.XPClass getClass()
}

New API

public class util.UUID extends lang.Object {
  public static util.UUID::$NS_DNS
  public static util.UUID::$NS_URL
  public static util.UUID::$NS_OID
  public static util.UUID::$NS_X500
  public util.UUID::$time_low
  public util.UUID::$time_mid
  public util.UUID::$time_hi_and_version
  public util.UUID::$clock_seq_low
  public util.UUID::$clock_seq_hi_and_reserved
  public util.UUID::$node
  protected util.UUID::$version

  public util.UUID __construct(var $arg) throws lang.FormatException

  public static util.UUID timeUUID()
  public static util.UUID md5UUID(util.UUID $namespace, string $name)
  public static util.UUID sha1UUID(util.UUID $namespace, string $name)
  public static util.UUID randomUUID()

  public int version()
  public lang.types.Bytes getBytes()
  public string getUrn()
  public string toString()
  public string hashCode()
  public bool equals(var $cmp)
  public string getClassName()
  public lang.XPClass getClass()
}

The constructor accepts one of the following, all of which are equivalent:

<?php
  new UUID('6ba7b811-9dad-11d1-80b4-00c04fd430c8');
  new UUID('{6ba7b811-9dad-11d1-80b4-00c04fd430c8}');
  new UUID('urn:uuid:6ba7b811-9dad-11d1-80b4-00c04fd430c8');
  new UUID(new Bytes("k\xa7\xb8\x11\x9d\xad\x11\xd1\x80\xb4\x00\xc0O\xd40\xc8"));
?>

The input formats seen above can be retrieved via the following:

<?php
  $uuid->hashCode(); // '6ba7b811-9dad-11d1-80b4-00c04fd430c8'
  $uuid->toString(); // '{6ba7b811-9dad-11d1-80b4-00c04fd430c8}'
  $uuid->getUrn();   // 'urn:uuid:6ba7b811-9dad-11d1-80b4-00c04fd430c8'
  $uuid->getBytes(); // new Bytes("k\xa7\xb8\x11\x9d\xad\x11\xd1\x80\xb4\x00\xc0O\xd40\xc8")
?>

Security considerations

n/a

Speed impact

n/a

Dependencies

n/a

Related documents

RFC #210
http://docs.oracle.com/javase/6/docs/api/java/util/UUID.html
http://commons.apache.org/sandbox/id/apidocs/org/apache/commons/id/uuid/UUID.html
http://docs.python.org/library/uuid.html
http://uuidtools.rubyforge.org/api/classes/UUIDTools/UUID.html
http://msdn.microsoft.com/en-us/library/system.guid.aspx

[kiesel]

+1

[thekid]

The UUID class' new API introduces two BC breaks - these could be worked around by re-adding create() as alias for timeUUID() (and deprecating it at the same time) and by switching hashCode() and toString()'s return values.