svn commit: r1709874 - /directory/site/trunk/content/api/user-guide/6.27-oid.mdtext

[el...@apache.org]

Author: elecharny
Date: Wed Oct 21 16:00:38 2015
New Revision: 1709874

URL: http://svn.apache.org/viewvc?rev=1709874&view=rev
Log:
Added a page for the OID class

Modified:
    directory/site/trunk/content/api/user-guide/6.27-oid.mdtext

Modified: directory/site/trunk/content/api/user-guide/6.27-oid.mdtext
URL: http://svn.apache.org/viewvc/directory/site/trunk/content/api/user-guide/6.27-oid.mdtext?rev=1709874&r1=1709873&r2=1709874&view=diff
==============================================================================
--- directory/site/trunk/content/api/user-guide/6.27-oid.mdtext (original)
+++ directory/site/trunk/content/api/user-guide/6.27-oid.mdtext Wed Oct 21 16:00:38 2015
@@ -24,4 +24,58 @@ Notice: Licensed to the Apache Software
 
 # 6.27 - Oid
 
->**Note:** Contents for this page will be added soon...
\ No newline at end of file
+## Introduction
+
+An *OID* stands for *Object* *ID*entifier. It's a part of the *ASN/1*  standard. Basically, it's a hierarchy, named a 'registration tree'. It's a list of 'arcs', which values start at '0', and each arc is separated with a dot ( '.' ).
+
+There are three defined root arcs :
+
+    * itu-t (0)
+    * iso (1)
+    * joint-iso-itu-t (2) 
+
+There is some places on the internet where one can have a look at the existing OIDs. Here is one : [OID repository](http://www.oid-info.com/cgi-bin/display?tree=&see=all).
+
+## Syntax
+
+The OID syntax is pretty simple : some numbers with dots between them, like 0.1.245
+
+There are a few extra rules :
+
+    * The first number must be 0, 1 or 2
+    * If it's 0 or 1, then the second number must be between 0 and 39
+    * A dot must be preceded and followed by a number
+    * A 0 at first position is never followed by any other digit
+    * There is no limit for the number of digits otherwise : 2.25.81407072025111374527560065493494091452 is legit
+
+## API
+
+The *Apache LDAP API* offers a few functions which can be used to manipulate an OID. In any case, we don't have a constructor for an OID.
+
+The class to use is *org.apache.directory.api.asn1.util.Oid*. It creates immutable instances.
+
+### static Oid fromBytes( byte[] )
+
+Returns an *Oid* instance constructed using a *byte[]* representing an encoded OID.
+
+### static Oid fromString( String )
+
+Returns an *Oid* instance constructed from a *String* representing an OID.
+
+### static boolean isOid( String )
+
+Tells if a *String* is a valid OID.
+
+### String toString()
+
+Return the *String* representation of an *Oid* instance.
+
+### byte[] toBytes()
+
+Return the *byte[]* representation of an *Oid* instance.
+
+## OID parsing
+
+We use a *FSA* (Finite State Automaton) to parse a String to get an internal representation of an OID. Here is a picture showing the *FSA* we are using :
+
+![OID FSA](images/OID-state-automaton.png)