directory-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ersi...@apache.org
Subject svn commit: r372968 [2/6] - in /directory/trunks/apacheds/src/site: ./ resources/ resources/developers/ resources/images/ resources/users/ xdoc/ xdoc/developers/ xdoc/drafts/ xdoc/images/ xdoc/projects/ xdoc/rfcs/ xdoc/users/
Date Fri, 27 Jan 2006 20:13:36 GMT
Added: directory/trunks/apacheds/src/site/xdoc/developers/aci_aciitemabnf.xml
URL: http://svn.apache.org/viewcvs/directory/trunks/apacheds/src/site/xdoc/developers/aci_aciitemabnf.xml?rev=372968&view=auto
==============================================================================
--- directory/trunks/apacheds/src/site/xdoc/developers/aci_aciitemabnf.xml (added)
+++ directory/trunks/apacheds/src/site/xdoc/developers/aci_aciitemabnf.xml Fri Jan 27 12:11:10 2006
@@ -0,0 +1,198 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<document>
+  <properties>
+    <author email="ersiner">ersiner</author>
+    
+  </properties>
+  <body>
+    <p>
+The ABNF syntax for LDAP ACIItem is as
+follows:</p>
+    <source>ACIItem = "{" sp aci_identificationTag
+              sep sp aci-precedence
+              sep sp aci-authenticationLevel
+              sep sp aci-itemOrUserFirst sp "}"
+
+aci_identificationTag   = id-identificationTag msp DirectoryString
+
+aci-precedence          = id-precedence msp Precedence
+
+aci-authenticationLevel = id-authenticationLevel msp AuthenticationLevel
+
+aci-itemOrUserFirst = id-itemOrUserFirst msp aci-itemOrUserFirst
+
+aci-itemOrUserFirst = aci-itemFirst / aci-userFirst
+
+aci-itemFirst       = id-itemFirst ":" ItemFirst
+
+aci-userFirst       = id-userFirst ":" UserFirst
+
+ItemFirst = "{" sp aci-protectedItems
+                sep sp aci-itemPermissions sp "}"
+
+UserFirst = "{" sp aci-userClasses
+                sep sp aci-userPermissions sp "}"
+
+aci-protectedItems    = id-protectedItems msp ProtectedItems
+
+aci-itemPermissions   = id-itemPermissions msp ItemPermissions
+
+aci-userClasses       = id-userClasses msp UserClasses
+
+aci-userPermissions   = id-userPermissions msp UserPermissions
+
+ProtectedItems = "{" [ sp aci-entry]
+                     [ sep sp aci-allUserAttributeTypes ]
+                     [ sep sp aci-attributeType ]
+                     [ sep sp aci-allAttributeValues ] 
+                     [ sep sp aci-allUserAttributeTypesAndValues ]
+                     [ sep sp aci-attributeValue ]
+                     [ sep sp aci-selfValue ]
+                     [ sep sp aci-rangeOfValues ]
+                     [ sep sp aci-maxValueCount ]
+                     [ sep sp aci-maxImmSub ]
+                     [ sep sp aci-restrictedBy ]
+                     [ sep sp aci-classes ] sp "}"
+
+ItemPermissions = "{" [ sp ItemPermission
+                        *( sep sp ItemPermission ) sp "}"
+
+ItemPermission = "{" [ sp aci-precedence ]
+                       sep sp aci-userClasses
+                       sep sp aci-grantsAndDenials sp "}"
+
+UserClasses = "{" [ sp aci-allUsers ]
+                  [ sep sp aci-thisEntry ]
+                  [ sep sp aci-Name ]
+                  [ sep sp aci-userGroup ]
+                  [ sep sp aci-subtree ] sp "}"
+
+UserPermissions = "{" [ sp UserPermission
+                        *( sep sp UserPermission ) ] sp "}" 
+
+UserPermission = "{" [ sp aci-precedence ]
+                       sep sp aci-protectedItems
+                       sep sp aci-grantsAndDenials sp "}"
+
+aci-entry                          = id-entry
+
+aci-allUserAttributeTypes          = id-allUserAttributeTypes
+
+aci-attributeType                  = id-attributeType msp AttributeTypes
+
+aci-allAttributeValues             = id-allAttributeValues msp AttributeTypes
+
+aci-allUserAttributeTypesAndValues = id-allUserAttributeTypesAndValues
+
+aci-attributeValue                 = id-attributeValue msp AttributeTypeAndValues
+
+aci-selfValue                      = id-selfValue msp AttributeTypes
+
+aci-rangeOfValues                  = id-rangeOfValues msp Filter
+
+aci-maxValueCount                  = id-maxValueCount msp MaxValueCount
+
+aci-maxImmSub                      = id-maxImmSub msp INTEGER
+
+aci-restrictedBy                   = id-restrictedBy msp RestrictedBy
+
+aci-classes                        = id-classes msp Refinement
+
+aci-grantsAndDenials               = id-grantsAndDenials msp GrantsAndDenials
+
+aci-allUsers                       = id-allUsers
+
+aci-thisEntry                      = id-thisEntry
+
+aci-name                           = id-name msp DistinguishedNames
+
+aci-userGroup                      = id-userGroup msp DistinguishedNames
+
+aci-subtree                        = id-subtree msp SubtreeSpecifications
+
+AttributeTypes = "{" sp AttributeType
+                     *( sep sp AttributeType ) sp "}"
+                     
+AttributeTypeAndValues = "{" sp AttributeTypeAndValue
+                             *( sep sp AttributeTypeAndValue ) sp "}"
+
+MaxValueCount = "{" sp AttributeType
+                    sep sp INTEGER sp "}"
+
+RestrictedBy = "{" sp RestrictedValue
+                   *( sep sp RestrictedValue ) sp "}"
+
+GrantsAndDenials = "{" [ sp GrantAndDenialsBit
+                         *( sep sp GrantAndDenialsBit ) ] sp "}"
+                   ; WARNING: There SHALL NOT be any duplicates
+
+DistinguishedNames = "{" sp DistinguishedName
+                         *( sep sp DistinguishedName ) sp "}"
+                        
+
+SubtreeSpecifications = "{" sp SubtreeSpecification
+                            *( sep sp SubtreeSpecification ) sp "}"
+
+RestrictedValue = "{" sp aci-type
+                      sep sp aci-valuesIn "}"
+
+aci-type     = id-type msp AttributeType
+
+aci-valuesIn = id-valuesIn msp AttributeType
+
+Precedence   = INTEGER(1..255) ; FIXME: How shall we show this ?
+
+AuthenticationLevel = id-none / id-simple / id-strong
+
+GrantAndDenialsBit = id-grantAdd
+                     / id-denyAdd
+                     / id-grantDiscloseOnError
+                     / id-denyDiscloseOnError
+                     / id-grantRead
+                     / id-denyRead
+                     / id-grantRemove
+                     / id-denyRemove
+                     / id-grantBrowse
+                     / id-denyBrowse
+                     / id-grantExport
+                     / id-denyExport
+                     / id-grantImport
+                     / id-denyImport
+                     / id-grantModify
+                     / id-denyModify
+                     / id-grantRename
+                     / id-denyRename
+                     / id-grantReturnDN
+                     / id-denyReturnDN
+                     / id-grantCompare
+                     / id-denyCompare
+                     / id-grantFilterMatch
+                     / id-denyFilterMatch
+                     / id-grantInvoke
+                     / id-denyInvoke
+
+;MYRULE
+;id-X = "X"
+</source>
+    <table>
+      <tr>
+        <th>
+          <img src="http://docs.safehaus.org/images/icons/emoticons/information.png"/>
+        </th>
+        <th>
+          <center>The Apache Directory Server way...</center>
+        </th>
+      </tr>
+      <tr>
+        <td/>
+        <td>
+          <p>
+Apache Directory Server allows a fully flexible version of this grammar where
+order of named components and amount of spaces (where applicable) do not
+matter.</p>
+        </td>
+      </tr>
+    </table>
+  </body>
+</document>

Added: directory/trunks/apacheds/src/site/xdoc/developers/aci_aciitemasn1.xml
URL: http://svn.apache.org/viewcvs/directory/trunks/apacheds/src/site/xdoc/developers/aci_aciitemasn1.xml?rev=372968&view=auto
==============================================================================
--- directory/trunks/apacheds/src/site/xdoc/developers/aci_aciitemasn1.xml (added)
+++ directory/trunks/apacheds/src/site/xdoc/developers/aci_aciitemasn1.xml Fri Jan 27 12:11:10 2006
@@ -0,0 +1,546 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<document>
+  <properties>
+    <author email="ersiner">ersiner</author>
+    
+  </properties>
+  <body>
+    <section heading="h1" name="ACIItem grammar">
+      <subsection heading="h2" name="ASN.1 Grammar">
+        <p>
+The ASN.1 syntax for ACIItem of X.501 as given in the specificiation is as
+follows</p>
+        <source>ACIItem ::= SEQUENCE {
+	identificationTag DirectoryString { ub-tag },
+	precedence Precedence,
+	authenticationLevel AuthenticationLevel,
+	itemOrUserFirst CHOICE {
+		itemFirst [0] SEQUENCE {
+			protectedItems ProtectedItems,
+			itemPermissions SET OF ItemPermission },
+		userFirst [1] SEQUENCE {
+			userClasses UserClasses,
+			userPermissions SET OF UserPermission } } }
+
+Precedence ::= INTEGER (0..255)
+
+ProtectedItems ::= SEQUENCE {
+	entry                          [0] NULL OPTIONAL,
+	allUserAttributeTypes          [1] NULL OPTIONAL,
+	attributeType                  [2] SET SIZE (1..MAX) OF AttributeType OPTIONAL,
+	allAttributeValues             [3] SET SIZE (1..MAX) OF AttributeType OPTIONAL,
+	allUserAttributeTypesAndValues [4] NULL OPTIONAL,
+	attributeValue                 [5] SET SIZE (1..MAX) OF AttributeTypeAndValue OPTIONAL,
+	selfValue                      [6] SET SIZE (1..MAX) OF AttributeType OPTIONAL,
+	rangeOfValues                  [7] Filter OPTIONAL,
+	maxValueCount                  [8] SET SIZE (1..MAX) OF MaxValueCount OPTIONAL,
+	maxImmSub                      [9] INTEGER OPTIONAL,
+	restrictedBy                   [10] SET SIZE (1..MAX) OF RestrictedValue OPTIONAL,
+	contexts                       [11] SET SIZE (1..MAX) OF ContextAssertion OPTIONAL,
+	classes                        [12] Refinement OPTIONAL }
+
+MaxValueCount ::= SEQUENCE {
+	type AttributeType,
+	maxCount INTEGER }
+
+RestrictedValue ::= SEQUENCE {
+	type AttributeType,
+	valuesIn AttributeType }
+
+UserClasses ::= SEQUENCE {
+	allUsers  [0] NULL OPTIONAL,
+	thisEntry [1] NULL OPTIONAL,
+	name      [2] SET SIZE (1..MAX) OF NameAndOptionalUID OPTIONAL,
+	userGroup [3] SET SIZE (1..MAX) OF NameAndOptionalUID OPTIONAL,
+		-- dn component shall be the name of an
+		-- entry of GroupOfUniqueNames
+	subtree   [4] SET SIZE (1..MAX) OF SubtreeSpecification OPTIONAL }
+
+ItemPermission ::= SEQUENCE {
+	precedence Precedence OPTIONAL,
+		-- defaults to precedence in ACIItem
+	userClasses UserClasses,
+	grantsAndDenials GrantsAndDenials }
+
+UserPermission ::= SEQUENCE {
+	precedence Precedence OPTIONAL,
+		-- defaults to precedence in ACIItem
+	protectedItems ProtectedItems,
+	grantsAndDenials GrantsAndDenials }
+
+AuthenticationLevel ::= CHOICE {
+	basicLevels SEQUENCE {
+	level ENUMERATED { none (0), simple (1), strong (2) },
+	localQualifier INTEGER OPTIONAL,
+	signed BOOLEAN DEFAULT FALSE },
+	other EXTERNAL }
+
+GrantsAndDenials ::= BIT STRING {
+	-- permissions that may be used in conjunction
+	-- with any component of ProtectedItems
+	grantAdd             (0),
+	denyAdd              (1),
+	grantDiscloseOnError (2),
+	denyDiscloseOnError  (3),
+	grantRead            (4),
+	denyRead             (5),
+	grantRemove          (6),
+	denyRemove           (7),
+	-- permissions that may be used only in conjunction
+	-- with the entry component
+	grantBrowse          (8),
+	denyBrowse           (9),
+	grantExport          (10),
+	denyExport           (11),
+	grantImport          (12),
+	denyImport           (13),
+	grantModify          (14),
+	denyModify           (15),
+	grantRename          (16),
+	denyRename           (17),
+	grantReturnDN        (18),
+	denyReturnDN         (19),
+	-- permissions that may be used in conjunction
+	-- with any component, except entry, of ProtectedItems
+	grantCompare         (20),
+	denyCompare          (21),
+	grantFilterMatch     (22),
+	denyFilterMatch      (23),
+	grantInvoke          (24),
+	denyInvoke           (25) }
+
+AttributeTypeAndValue ::= SEQUENCE {
+	type ATTRIBUTE.&amp;id ({SupportedAttributes}),
+	value ATTRIBUTE.&amp;Type({SupportedAttributes}{@type}) }
+</source>
+      </subsection>
+      <subsection heading="h2" name="BNF grammar">
+        <p>
+Here is the BNF grammar of this ASN.1 grammar
+:</p>
+        <source>&lt;wrapperEntryPoint&gt; ::= &lt;theACIItem&gt; EOF
+
+&lt;theACIItem&gt; ::= 
+    '{'
+        &lt;spse&gt; &lt;aci_identificationTag&gt; &lt;spse&gt;
+        ',' &lt;spse&gt; &lt;aci_precedence&gt; &lt;spse&gt;
+        ',' &lt;spse&gt; &lt;aci_authenticationLevel&gt; &lt;spse&gt;
+        ',' &lt;spse&gt; &lt;aci_itemOrUserFirst&gt; &lt;spse&gt;
+    '}'
+
+&lt;aci_identificationTag&gt; ::= "identificationTag" &lt;sps&gt; SAFEUTF8STRING
+
+&lt;aci_precedence&gt; ::= "precedence" &lt;sps&gt; INTEGER
+
+&lt;aci_authenticationLevel&gt; ::= "authenticationLevel" &lt;sps&gt; &lt;basicLevels&gt;
+
+&lt;basicLevels&gt; ::= "basicLevels" &lt;spse&gt; ':' &lt;spse&gt; '{' &lt;spse&gt; &lt;level&gt; &lt;spse&gt; &lt;level_follower&gt; '}'
+
+&lt;level&gt; ::= "level" &lt;sps&gt; &lt;levels&gt;
+
+&lt;levels&gt; ::= "none" | "simple" | "strong"
+
+&lt;level_follower&gt; ::= ',' &lt;spse&gt; &lt;localQualifier_signed&gt; | e
+
+&lt;localQualifier_signed&gt; ::= 
+    "localQualifier" &lt;sps&gt; INTEGER &lt;spse&gt; &lt;signed_e&gt;
+    | "signed" &lt;sps&gt; &lt;booleanValue&gt; &lt;spse&gt; 
+
+&lt;signed_e&gt; ::= ',' &lt;spse&gt; "signed" &lt;sps&gt; &lt;booleanValue&gt; &lt;spse&gt; | e
+
+&lt;booleanValue&gt; ::= "FALSE" | "TRUE"
+
+&lt;aci_itemOrUserFirst&gt; ::= "itemOrUserFirst" &lt;sps&gt; &lt;itemOrUserFirst&gt;
+
+&lt;itemOrUserFirst&gt; ::= &lt;itemFirst&gt; | &lt;userFirst&gt;
+
+&lt;itemFirst&gt; ::= "itemFirst" ':' '{' &lt;spse&gt; &lt;protectedItems&gt; ',' &lt;spse&gt; &lt;itemPermissions&gt; &lt;spse&gt; '}'
+
+&lt;userFirst&gt; ::= "userFirst" ':' '{' &lt;spse&gt; &lt;userClasses&gt; ',' &lt;spse&gt; &lt;userPermissions&gt; &lt;spse&gt; '}'
+
+&lt;protectedItems&gt; ::= "protectedItems" &lt;spse&gt; '{' &lt;spse&gt; &lt;protectedItems_e&gt; &lt;spse&gt; '}'
+
+&lt;protectedItems_e&gt; ::= "entry" &lt;entry_follower_e&gt;
+                	| "allUserAttributeTypes" &lt;allUserAttributeTypes_follower_e&gt;
+                	| &lt;attributeType&gt; &lt;attributeType_follower_e&gt;
+                	| &lt;allAttributeValues&gt; &lt;allAttributeValues_follower_e&gt;
+                	| &lt;allUserAttributeTypesAndValues&gt; &lt;allUserAttributeTypesAndValues_follower_&gt;
+                	| ATTRIBUTE_VALUE_CANDIDATE &lt;attributeValue_follower_e&gt;
+                	| &lt;selfValue&gt; &lt;selfValue_follower_e&gt;
+                	| RANGE_OF_VALUES_CANDIDATE &lt;rangeOfValues_follower_e&gt;
+                	| &lt;maxValueCount&gt; &lt;maxValueCount_follower_e&gt;
+                	| &lt;maxImmSub&gt; &lt;maxImmSub_follower_e&gt;
+                	| &lt;restrictedBy&gt; &lt;restrictedBy_follower_e&gt;
+                	| &lt;classes&gt;
+			| e
+
+&lt;entry_follower_e&gt; ::= ',' &lt;spse&gt; &lt;entry_follower&gt; | e
+
+&lt;entry_follower&gt; ::= 
+	"allUserAttributeTypes" &lt;allUserAttributeTypes_follower_e&gt;
+            | &lt;attributeType&gt; &lt;attributeType_follower_e&gt;
+            | &lt;allAttributeValues&gt; &lt;allAttributeValues_follower_e&gt; 
+            | &lt;allUserAttributeTypesAndValues&gt; &lt;allUserAttributeTypesAndValues_follower_e&gt;
+            | ATTRIBUTE_VALUE_CANDIDATE &lt;attributeValue_follower_e&gt;
+            | &lt;selfValue&gt; &lt;selfValue_follower_e&gt;
+            | RANGE_OF_VALUES_CANDIDATE &lt;rangeOfValues_follower_e&gt;
+            | &lt;maxValueCount&gt; &lt;maxValueCount_follower_e&gt;
+            | &lt;maxImmSub&gt; &lt;maxImmSub_follower_e&gt;
+            | &lt;restrictedBy&gt; &lt;restrictedBy_follower_e&gt;
+            | &lt;classes&gt;
+
+&lt;allUserAttributeTypes_follower_e&gt; ::= ',' &lt;spse&gt; &lt;allUserAttributeTypes_follower&gt; | e
+
+&lt;allUserAttributeTypes_follower&gt; ::=
+            &lt;attributeType&gt; &lt;attributeType_follower_e&gt;
+            | &lt;allAttributeValues&gt; &lt;allAttributeValues_follower_e&gt;
+            | &lt;allUserAttributeTypesAndValues&gt; &lt;allUserAttributeTypesAndValues_follower_e&gt;
+            | ATTRIBUTE_VALUE_CANDIDATE &lt;attributeValue_follower_e&gt;
+            | &lt;selfValue&gt; &lt;selfValue_follower_e&gt;
+            | RANGE_OF_VALUES_CANDIDATE &lt;rangeOfValues_follower_e&gt;
+            | &lt;maxValueCount&gt; &lt;maxValueCount_follower_e&gt;
+            | &lt;maxImmSub&gt; &lt;maxImmSub_follower_e&gt;
+            | &lt;restrictedBy&gt; &lt;restrictedBy_follower_e&gt;
+            | &lt;classes&gt;
+
+&lt;attributeType_follower_e&gt; ::= ',' &lt;spse&gt; &lt;attributeType_follower&gt; | e
+&lt;attributeType_follower&gt; ::= 
+            &lt;allAttributeValues&gt; &lt;allAttributeValues_follower_e&gt;
+            | &lt;allUserAttributeTypesAndValues&gt; &lt;allUserAttributeTypesAndValues_follower_e&gt;
+            | ATTRIBUTE_VALUE_CANDIDATE &lt;attributeValue_follower_e&gt;
+            | &lt;selfValue&gt; &lt;selfValue_follower_e&gt;
+            | RANGE_OF_VALUES_CANDIDATE &lt;rangeOfValues_follower_e&gt;
+            | &lt;maxValueCount&gt; &lt;maxValueCount_follower_e&gt;
+            | &lt;maxImmSub&gt; &lt;maxImmSub_follower_e&gt;
+            | &lt;restrictedBy&lt; &lt;restrictedBy_follower_e&gt;
+            | &lt;classes&gt;
+
+&lt;allAttributeValues_follower_e&gt; ::= ',' &lt;spse&gt; &lt;allAttributeValues_follower&gt; | e
+
+&lt;allAttributeValues_follower&gt; ::= 
+            &lt;allUserAttributeTypesAndValues&gt; &lt;allUserAttributeTypesAndValues_follower_e&gt;
+            | ATTRIBUTE_VALUE_CANDIDATE &lt;attributeValue_follower_e&gt;
+            | &lt;selfValue&gt; &lt;selfValue_follower_e&gt;
+            | RANGE_OF_VALUES_CANDIDATE &lt;rangeOfValues_follower_e&gt;
+            | &lt;maxValueCount&gt; &lt;maxValueCount_follower_e&gt;
+            | &lt;maxImmSub&gt; &lt;maxImmSub_follower_e&gt;
+            | &lt;restrictedBy&gt; &lt;restrictedBy_follower_e&gt;
+            | &lt;classes&gt;
+
+&lt;allUserAttributeTypesAndValues_follower_e&gt; ::= ',' &lt;spse&gt; &lt;allUserAttributeTypesAndValues_follower&gt; | e
+
+&lt;allUserAttributeTypesAndValues_follower&gt; ::= 
+            ATTRIBUTE_VALUE_CANDIDATE &lt;attributeValue_follower_e&gt;
+            | &lt;selfValue&gt; &lt;selfValue_follower_e&gt;
+            | RANGE_OF_VALUES_CANDIDATE &lt;rangeOfValues_follower_e&gt;
+            | &lt;maxValueCount&gt; &lt;maxValueCount_follower_e&gt;
+            | &lt;maxImmSub&gt; &lt;maxImmSub_follower_e&gt;
+            | &lt;restrictedBy&gt; &lt;restrictedBy_follower_e&gt;
+            | &lt;classes&gt;
+
+&lt;attributeValue_follower_e&gt; ::= ',' &lt;spse&gt; &lt;attributeValue_follower&gt; | e
+
+&lt;attributeValue_follower&gt; ::= 
+            &lt;selfValue&gt; &lt;selfValue_follower_e&gt;
+            | RANGE_OF_VALUES_CANDIDATE &lt;rangeOfValues_follower_e&gt;
+            | &lt;maxValueCount&gt; &lt;maxValueCount_follower_e&gt;
+            | &lt;maxImmSub&gt; &lt;maxImmSub_follower_e&gt;
+            | &lt;restrictedBy&gt; &lt;restrictedBy_follower_e&gt;
+            | &lt;classes&gt;
+
+&lt;selfValue_follower&gt; ::= ',' &lt;spse&gt; &lt;selfValue_follower&gt; | e
+
+&lt;selfValue_follower&gt; ::= 
+            RANGE_OF_VALUES_CANDIDATE &lt;rangeOfValues_follower_e&gt;
+            | &lt;maxValueCount&gt; &lt;maxValueCount_follower_e&gt;
+            | &lt;maxImmSub&gt; &lt;maxImmSub_follower_e&gt;
+            | &lt;restrictedBy&gt; &lt;restrictedBy_follower_e&gt;
+            | &lt;classes&gt;
+
+&lt;rangeOfValues_follower&gt; ::= ',' &lt;spse&gt; &lt;rangeOfValues_follower&gt; | e
+
+&lt;rangeOfValues_follower&gt; ::= 
+            &lt;maxValueCount&gt; &lt;maxValueCount_follower_e&gt;
+            | &lt;maxImmSub&gt; &lt;maxImmSub_follower_e&gt;
+            | &lt;restrictedBy&gt; &lt;restrictedBy_follower_e&gt;
+            | &lt;classes&gt;
+
+&lt;maxValueCount_follower&gt; ::= ',' &lt;spse&gt; &lt;maxValueCount_follower&gt; | e
+
+&lt;maxValueCount_follower&gt; ::= 
+            &lt;maxImmSub&gt; &lt;maxImmSub_follower_e&gt;
+            | &lt;restrictedBy&gt; &lt;restrictedBy_follower_e&gt;
+            | &lt;classes&gt;
+
+&lt;maxImmSub_follower&gt; ::= ',' &lt;spse&gt; &lt;maxImmSub_follower&gt; | e
+
+&lt;maxImmSub_follower&gt; ::= 
+	    &lt;restrictedBy&gt; &lt;restrictedBy_follower&gt;
+            | &lt;classes&gt;
+
+&lt;restrictedBy_follower&gt; ::= ',' &lt;spse&gt; &lt;classes&gt; | e
+
+&lt;attributeType&gt; ::= "attributeType" &lt;sps&gt; &lt;attributeTypeSet&gt;
+
+&lt;allAttributeValues&gt; ::= "allAttributeValues" &lt;sps&gt; &lt;attributeTypeSet&gt;
+
+&lt;allUserAttributeTypesAndValues&gt; ::= "allUserAttributeTypesAndValues"
+
+&lt;selfValue&gt; ::= "selfValue" &lt;sps&gt; &lt;attributeTypeSet&gt;
+
+&lt;maxValueCount&gt; ::= "maxValueCount" &lt;sps&gt; '{' &lt;spse&gt; &lt;aMaxValueCount&gt; &lt;spse&gt; &lt;aMaxValueCounts&gt; '}'
+
+&lt;aMaxValueCounts&gt; ::= ',' &lt;spse&gt; &lt;aMaxValueCount&gt; &lt;spse&gt; &lt;aMaxValueCounts&gt; | e
+
+&lt;aMaxValueCount&gt; ::= '{' &lt;spse&gt; "type" &lt;sps&gt; &lt;oid&gt; &lt;spse&gt; ',' &lt;spse&gt; "maxCount" &lt;sps&gt; INTEGER &lt;spse&gt; '}'
+
+&lt;maxImmSub&gt; ::= "maxImmSub" &lt;sps&gt; INTEGER
+
+&lt;restrictedBy&gt; ::= "restrictedBy" &lt;sps&gt; '{' &lt;spse&gt; &lt;restrictedValue&gt; &lt;spse&gt; &lt;restrictedValues&gt; '}'
+
+&lt;restrictedValues&gt; ::= ',' &lt;spse&gt; &lt;restrictedValue&gt; &lt;spse&gt; &lt;restrictedValues&gt; | e
+
+&lt;restrictedValue&gt; ::= '{' &lt;spse&gt; "type" &lt;sps&gt; &lt;oid&gt; &lt;spse&gt; ',' &lt;spse&gt; "valuesIn" &lt;sps&gt; &lt;oid&gt; &lt;spse&gt; '}'
+
+&lt;attributeTypeSet&gt; ::= '{' &lt;spse&gt; &lt;oid&gt; &lt;spse&gt; &lt;attributeTypeSets&gt; '}'
+
+&lt;attributeTypeSets&gt; ::= ',' &lt;spse&gt; &lt;oid&gt; &lt;spse&gt; &lt;attributeTypeSet&gt; | e
+
+&lt;classes&gt; ::= "classes" &lt;sps&gt; &lt;refinement&gt;
+
+&lt;itemPermissions&gt; ::= "itemPermissions" &lt;sps&gt; '{' &lt;spse&gt; &lt;itemPermission_e&gt; '}'
+
+&lt;itemPermission_e&gt; ::= &lt;itemPermission&gt; &lt;spse&gt; &lt;itemPermissions_e&gt; | e
+
+&lt;itemPermissions_e&gt; ::= ',' &lt;spse&gt; &lt;itemPermission&gt; &lt;spse&gt; &lt;itemPermissions_e&gt; | e
+
+&lt;itemPermission&gt; ::= '{' &lt;spse&gt; &lt;precedence_e&gt; &lt;spse&gt; '}'
+
+&lt;precedence_e&gt; ::= 
+    "precedence" &lt;sps&gt; INTEGER &lt;spse&gt; ',' &lt;spse&gt; &lt;userClasses&gt; &lt;spse&gt; ',' &lt;spse&gt; &lt;grantsAndDenials&gt;
+    | &lt;userClasses&gt; &lt;spse&gt; ',' &lt;spse&gt; &lt;grantsAndDenials&gt;
+
+&lt;grantsAndDenials&gt; ::= "grantsAndDenials" &lt;sps&gt; '{' &lt;spse&gt; &lt;grantAndDenialsBit_e&gt; '}'
+
+&lt;grantAndDenialsBit_e&gt; ::= &lt;grantAndDenialsBit&gt; &lt;spse&gt; &lt;grantAndDenialsBits_e&gt; | e
+
+&lt;grantAndDenialsBits_e&gt; ::= ',' &lt;spse&gt; &lt;grantAndDenialsBit&gt; &lt;spse&gt; &lt;grantAndDenialsBits_e&gt; | e
+
+&lt;grantAndDenialsBit&gt; ::= 
+    "grantAdd" // (0),
+    | "denyAdd" // (1),
+    | "grantDiscloseOnError" // (2),
+    | "denyDiscloseOnError" // (3),
+    | "grantRead" // (4),
+    | "denyRead" // (5),
+    | "grantRemove" // (6),
+    | "denyRemove" // (7),
+    | "grantBrowse" // (8),
+    | "denyBrowse" // (9),
+    | "grantExport" // (10),
+    | "denyExport" // (11),
+    | "grantImport" // (12),
+    | "denyImport" // (13),
+    | "grantModify" // (14),
+    | "denyModify" // (15),
+    | "grantRename" // (16),
+    | "denyRename" // (17),
+    | "grantReturnDN" // (18),
+    | "denyReturnDN" // (19),
+    | "grantCompare" // (20),
+    | "denyCompare" // (21),
+    | "grantFilterMatch" // (22),
+    | "denyFilterMatch" // (23),
+    | "grantInvoke" // (24),
+    | "denyInvoke" // (25)
+
+&lt;userClasses&gt; ::= "userClasses" &lt;sps&gt; '{' &lt;spse&gt; &lt;userClasses_e&gt; '}'
+
+&lt;userClasses_e&gt; ::= 
+            "allUsers" &lt;allUsers_follower_e&gt; &lt;spse&gt;
+            | "thisEntry" &lt;thisEntry_follower_e&gt; &lt;spse&gt;
+            | &lt;name&gt; &lt;name_follower_e&gt; &lt;spse&gt;
+            | &lt;userGroup&gt; &lt;userGroup_follower_e&gt; &lt;spse&gt;
+            | &lt;subtree&gt; &lt;spse&gt;
+	    | e
+
+&lt;allUsers_follower_e&gt; ::= ',' &lt;spse&gt; &lt;allUsers_follower&gt; | e
+
+&lt;allUsers_follower&gt; ::= 
+             "thisEntry" &lt;thisEntry_follower_e&gt;
+             | &lt;name&gt; &lt;name_follower_e&gt;
+             | &lt;userGroup&gt; &lt;userGroup_follower_e&gt;
+             | &lt;subtree&gt;
+
+&lt;thisEntry_follower_e&gt; ::= ',' &lt;spse&gt; &lt;thisEntry_follower&gt; | e
+
+&lt;thisEntry_follower&gt; ::= 
+            &lt;name&gt; &lt;name_follower_e&gt;
+            | &lt;userGroup&gt; &lt;userGroup_follower_e&gt;
+            | &lt;subtree
+
+&lt;name_follower&gt; ::= ',' &lt;spse&gt; &lt;name_follower&gt; | e
+
+&lt;name_follower&gt; ::= 
+            &lt;userGroup&gt; &lt;userGroup_follower_e&gt;
+            | &lt;subtree&gt;
+
+&lt;userGroup_follower_e&gt; ::= ',' &lt;spse&gt; &lt;subtree&gt; | e
+
+&lt;name&gt; ::= "name" &lt;sps&gt; '{' &lt;spse&gt; SAFEUTF8STRING &lt;spse&gt; &lt;names_e&gt; '}'
+
+&lt;names_e&gt; ::= ',' &lt;spse&gt; SAFEUTF8STRING &lt;spse&gt; &lt;names_e&gt; | e
+
+&lt;userGroup&gt; ::= "userGroup" &lt;sps&gt; '{' &lt;spse&gt; SAFEUTF8STRING &lt;spse&gt; &lt;userGroups_e&gt; '}'
+
+&lt;userGroups_e&gt; ::= ',' &lt;spse&gt; SAFEUTF8STRING &lt;spse&gt; &lt;userGroups_e&gt; | e
+
+&lt;subtree&gt; ::= "subtree" &lt;sps&gt; '{' &lt;spse&gt; &lt;subtreeSpecification&gt; &lt;spse&gt; &lt;subtrees_e&gt; '}'
+
+&lt;subtrees_e&gt; ::= ',' &lt;spse&gt; &lt;subtreeSpecification&gt; &lt;spse&gt; &lt;subtrees_e&gt; | e
+
+&lt;userPermissions&gt; ::= "userPermissions" &lt;sps&gt; '{' &lt;spse&gt; &lt;userPermissions_ee&gt; '}'
+
+&lt;userPermissions_ee&gt; ::= &lt;userPermission&gt; &lt;spse&gt; &lt;userPermissions_e&gt; | e
+
+&lt;userPermissions_e&gt; ::= ',' &lt;spse&gt; &lt;userPermission&gt; &lt;spse&gt; &lt;userPermissions_e&gt; | e
+
+&lt;userPermission&gt; ::= '{' &lt;spse&gt; &lt;precedence_ee&gt; &lt;spse&gt; '}'
+
+&lt;precedence_ee&gt; ::= 
+    "precedence" &lt;sps&gt; INTEGER &lt;spse&gt; ',' &lt;spse&gt; &lt;protectedItems&gt; &lt;spse&gt; ',' &lt;spse&gt; &lt;grantsAndDenials&gt;
+    | &lt;protectedItems&gt; &lt;spse&gt; ',' &lt;spse&gt; &lt;grantsAndDenials&gt;
+
+&lt;subtreeSpecification&gt; ::= '{' &lt;spse&gt; &lt;subtreeSpecification_e&gt; '}'
+
+&lt;subtreeSpecification_e&gt; ::= 
+	&lt;ss_base&gt; &lt;ss_base_follower_e&gt; &lt;spse&gt;
+        | &lt;ss_specificExclusions&gt; &lt;ss_specificExclusions_follower_e&gt; &lt;spse&gt;
+        | &lt;ss_minimum&gt; &lt;ss_minimum_follower_e&gt; &lt;spse&gt;
+        | &lt;ss_maximum&gt; &lt;ss_maximum_follower_e&gt; &lt;spse&gt;
+        | &lt;ss_specificationFilter&gt; &lt;spse&gt;
+	| e
+
+&lt;ss_base_follower_e&gt; ::= ',' &lt;spse&gt; &lt;ss_base_follower&gt; | e
+
+&lt;ss_base_follower&gt; ::= 
+            &lt;ss_specificExclusions&gt; &lt;ss_specificExclusions_follower_e&gt;
+            | &lt;ss_minimum&gt; &lt;ss_minimum_follower_e&gt;
+            | &lt;ss_maximum&gt; &lt;ss_maximum_follower_e&gt;
+            | &lt;ss_specificationFilter&gt;
+
+&lt;ss_specificExclusions_follower_e&gt; ::= ',' &lt;spse&gt; &lt;ss_specificExclusions_follower&gt; | e
+
+&lt;ss_specificExclusions_follower&gt; ::= 
+            &lt;ss_minimum&gt; &lt;ss_minimum_follower_e&gt;
+            | &lt;ss_maximum&gt; &lt;ss_maximum_follower_e&gt;
+            | &lt;ss_specificationFilter&gt;
+
+&lt;ss_minimum_follower_e&gt; ::= ',' &lt;spse&gt; &lt;ss_minimum_follower&gt; | e
+
+&lt;ss_minimum_follower&gt; ::= 
+            &lt;ss_maximum&gt; &lt;ss_maximum_follower_e&gt;
+            | &lt;ss_specificationFilter&gt;
+
+&lt;ss_maximum_follower_e&gt; ::= ',' &lt;spse&gt; &lt;ss_specificationFilter&gt; | e
+
+&lt;ss_base&gt; ::= "base" &lt;sps&gt; SAFEUTF8STRING
+
+&lt;ss_specificExclusions&gt; ::= "specificExclusions" &lt;sps&gt; &lt;specificExclusions&gt;
+
+&lt;specificExclusions&gt; ::= '{' &lt;spse&gt; &lt;specificExclusions_e&gt; '}'
+
+&lt;specificExclusions_e&gt; ::= &lt;specificExclusion&gt; &lt;spse&gt; &lt;specificExclusions_ee&gt; | e
+
+&lt;specificExclusions_ee&gt; ::= ',' &lt;spse&gt; &lt;specificExclusion&gt; &lt;spse&gt; &lt;specificExclusions_ee&gt; | e
+
+&lt;specificExclusion&gt; ::= "chopBefore" ':' SAFEUTF8STRING | "chopAfter" ':' SAFEUTF8STRING
+
+&lt;ss_minimum&gt; ::= "minimum" &lt;sps&gt; INTEGER
+
+&lt;ss_maximum&gt; ::= "maximum" &lt;sps&gt; INTEGER
+
+&lt;ss_specificationFilter&gt; ::= "specificationFilter" &lt;sps&gt; &lt;refinement&gt;
+
+&lt;oid&gt; ::= DESCR | NUMERICOID
+
+&lt;refinement&gt; ::= &lt;item&gt; | &lt;and&gt; | &lt;or&gt; | &lt;not&gt;
+
+&lt;item&gt; ::= "item" ':' &lt;oid&gt;
+
+&lt;and&gt; ::= "and" ':' &lt;refinements&gt;
+
+&lt;or&gt; ::= "or" ':' &lt;refinements&gt;
+
+&lt;not&gt; ::= "not" ':' &lt;refinements&gt;
+
+&lt;refinements&gt; ::= '{' &lt;spse&gt; &lt;refinements_e&gt; '}'
+
+&lt;refinements_e&gt; ::= &lt;refinement&gt; &lt;spse&gt; &lt;refinements_ee&gt; | e
+
+&lt;refinements_ee&gt; ::= ',' &lt;spse&gt; &lt;refinement&gt; &lt;spse&gt; &lt;refinements_ee&gt; | e
+
+&lt;sps&gt; ::= ' ' &lt;spse&gt;
+
+&lt;spse&gt; ::= ' ' &lt;spse&gt; | e
+
+
+
+
+// Lexer
+protected SAFEUTF8CHAR :
+    '\u0001'..'\u0021' |
+    '\u0023'..'\u007F' |
+    '\u00c0'..'\u00d6' |
+    '\u00d8'..'\u00f6' |
+    '\u00f8'..'\u00ff' |
+    '\u0100'..'\u1fff' |
+    '\u3040'..'\u318f' |
+    '\u3300'..'\u337f' |
+    '\u3400'..'\u3d2d' |
+    '\u4e00'..'\u9fff' |
+    '\uf900'..'\ufaff' ;
+
+',' : ',' ;
+
+' ' : ' ' ;
+
+':' : ':' ;
+
+protected DIGIT : '0' | LDIGIT ;
+
+protected LDIGIT : '1'..'9' ;
+
+protected ALPHA : 'A'..'Z' | 'a'..'z' ;
+
+protected INTEGER : DIGIT | ( LDIGIT ( DIGIT )+ ) ;
+
+protected HYPHEN : '-' ;
+
+protected NUMERICOID : INTEGER ( DOT INTEGER )+ ;
+
+protected DOT : '.' ;
+
+INTEGER_OR_NUMERICOID
+    :
+    ( INTEGER DOT ) =&gt; NUMERICOID
+    |
+    INTEGER
+    ;
+
+SAFEUTF8STRING : '"'! ( SAFEUTF8CHAR )* '"'! ;
+
+DESCR 
+    :
+    ( "attributeValue" ( ' '! )+ '{' ) =&gt;
+      "attributeValue"! ( ' '! )+ '{'! (options { greedy=false;}:. )* '}'!
+    | ( "rangeOfValues" ( ' '! )+ '(') =&gt;
+      "rangeOfValues"! ( ' '! )+ '(' (options { greedy=false;}:. )* ')'
+    | ALPHA ( ALPHA | DIGIT | HYPHEN )*
+    ;
+</source>
+      </subsection>
+    </section>
+  </body>
+</document>

Added: directory/trunks/apacheds/src/site/xdoc/developers/aci_implnotes.xml
URL: http://svn.apache.org/viewcvs/directory/trunks/apacheds/src/site/xdoc/developers/aci_implnotes.xml?rev=372968&view=auto
==============================================================================
--- directory/trunks/apacheds/src/site/xdoc/developers/aci_implnotes.xml (added)
+++ directory/trunks/apacheds/src/site/xdoc/developers/aci_implnotes.xml Fri Jan 27 12:11:10 2006
@@ -0,0 +1,290 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<document>
+  <properties>
+    <author email="akarasulu">akarasulu</author>
+    
+  </properties>
+  <body>
+    <section heading="h2" name="Introduction">
+      <p>
+Do not take this document as the final description of how we implement access
+controls within ApacheDS (yet).  It is just some notes that have been taken as
+we started implementing the access control subsystem.  Eventually it can be
+compiled into developer documentation on how the access control subsystem is
+implemented.</p>
+      <p>
+\\</p>
+      <p>
+\\</p>
+      <p>
+Too follow the JIRA tasks that lead to this feature take a look
+at
+        <a href="http://issues.apache.org/jira/browse/DIREVE-204">DIREVE-204</a>
+.
+      </p>
+    </section>
+    <section heading="h2" name="Access Control Subentry Operational Attribute">
+      <p>
+Although two kinds of subentry types exist for access control administrative
+areas (accessControlSpecificAreas and accessControlInnerAreas) we will still be
+using a single operational attribute within entries to reference the subentries
+of these areas.  We will use _accessControlSubentries_ as the identifier for the
+operational attribute containing the DN of subentries which the entry is within
+the scope of: meaning the subtreeSpecification associated with the referenced
+subentries select the entry.  Below is the schema definition for this new
+operational attribute which we have assigned off of the apache OID
+space:</p>
+      <source>attributetype ( 1.2.6.1.4.1.18060.1.1.1.3.26 NAME 'accessControlSubentries'
+    DESC 'Used to track a subentry associated with access control areas'
+    SUP distinguishedName
+    EQUALITY distinguishedNameMatch
+    SYNTAX 1.3.6.1.4.1.1466.115.121.1.12
+    SINGLE-VALUE
+    NO-USER-MODIFICATION
+    USAGE directoryOperation )
+</source>
+      <p>
+The subentry subsystem will automatically handle the injection of this attribute
+into normal entries as new subentries are added and altered.  This house keeping
+also tracks newly added normal entries making sure they have these operational
+attributes pointing to the appropriate
+subentries.</p>
+    </section>
+    <section heading="h2" name="Performance Considerations">
+      <p>
+An LDAP server should be read optimized.  Hence we cannot expect to parse
+lengthy ACIs into ACIITems then transform them into ACITuples for evaluation
+during a search operation.  This would considerably slow down search
+operations.</p>
+      <p>
+\\</p>
+      <p>
+\\</p>
+      <p>
+Instead of repeatedly preparing ACI information during search request processing
+the server will cache ACI information in the form of ACITuples.   ACI Tuples are
+an intermediate representation of ACIItems designed for the sake of making
+access control decisions within the Access Control Decision Function
+(ACDF).</p>
+      <p>
+\\</p>
+      <p>
+\\</p>
+      <table>
+        <tr>
+          <td>
+            <img src="http://docs.safehaus.org/images/icons/emoticons/warning.png"/>
+          </td>
+          <td>
+            <p>
+A set of ACITuples are generated from an ACIItem.  Sets of ACITuples can be
+mixed and evaluated together to represent the combined access control affects of
+one or more
+ACIItems.</p>
+          </td>
+        </tr>
+      </table>
+      <p>
+\\</p>
+      <p>
+\\</p>
+      <p>
+ApacheDS will use the multivalued perscriptiveACI attribute within access
+control subentries to contain multiple ACIItems.  The server can generate and
+combine the ACITuple sets of these ACITems within a single subentry to represent
+the next access control effects of that subentry.  This superset of ACITuples
+can be cached and associated with the DN of the subentry containing their
+respective ACIItems.  Hence during solidstate operation prescriptive ACIItems
+need not be parsed or transformed into ACITuple sets.  A simple lookup retrieves
+the ACITuple set for each access control subentry influencing an entry candidate
+to be returned to the client.  The ACDF is invoked with this ACITuple set
+(possibly combined with entryACI Tuplesets) and other information to quickly
+determine whether or not access is allowed during any operation not just a
+search
+operation.</p>
+    </section>
+    <section heading="h2" name="Cache Initialization and Upkeep">
+      <p>
+On startup the server must populate the cache with the set of ACITuples from
+respective access control subentries.  A search must be conducted for all access
+contol subentries in all namingContexts to discover the set of prescriptiveACIs
+defined within the
+server.</p>
+      <p>
+\\</p>
+      <p>
+\\</p>
+      <p>
+After initialization, during solid state operation, the cache must be kept up to
+date with prescriptiveACI deletions, modifications, and additions.  With the
+current interceptor based architecture we can easily keep track of these
+alterations by trapping add, delete, and modify operations on access control
+subentries.</p>
+      <p>
+\\</p>
+      <p>
+\\</p>
+      <p>
+Check out the following JIRA issues and commits for more information on how this
+was
+implemented:</p>
+      <ul nesting="1">
+        <li>
+          <a href="http://svn.apache.org/viewcvs.cgi?view=rev&amp;rev=290038">Commit 290038</a>
+        </li>
+        <li>
+          <a href="http://issues.apache.org/jira/browse/DIREVE-258">DIREVE-258</a>
+        </li>
+        <li>
+          <a href="http://issues.apache.org/jira/browse/DIREVE-259">DIREVE-259</a>
+        </li>
+      </ul>
+    </section>
+    <section heading="h2" name="Marker ObjectClass for Access Control Subentries">
+      <p>
+A marker objectClass is needed for tracking subentries containing
+prescriptiveACI attributes.  Looking at various drafts, RFCs and the X.500
+specifications there was very little to go on.  However we decided on the
+following
+objectClass:</p>
+      <p>
+\\</p>
+      <p>
+\\</p>
+      <source>objectclass ( 1.2.6.1.4.1.18060.1.1.1.4.100
+    NAME 'accessControlSubentry'
+    AUXILIARY 
+    MUST prescriptiveACI )
+</source>
+      <p>
+\\</p>
+      <p>
+\\</p>
+      <p>
+We chose the name because it matches the pattern used
+in
+        <a href="http://www.faqs.org/rfcs/rfc3671.html">RFC 3671</a>
+where the operational attribute used was collectiveAttributeSubentries and the
+marker objectClass was collectiveAttributeSubentry.  This makes the access
+control specific analogs consistent with this naming
+pattern.
+      </p>
+      <p>
+\\</p>
+      <p>
+\\</p>
+      <p>
+A perscriptiveACI attribute is included in the must list suggesting that at
+least one ACIItem must be contained by such an entry.  This is consistent with
+X.501 where at least one ACIITem is required for an access control subentry. 
+This leads us to have to define a prescriptiveACI
+attribute:</p>
+      <p>
+\\</p>
+      <p>
+\\</p>
+      <source>attributetype ( 1.2.6.1.4.1.18060.1.1.1.3.100 NAME 'prescriptiveACI'
+  DESC 'Access control information that applies to a set of entries'
+  EQUALITY directoryStringFirstComponentMatch
+  SYNTAX 1.3.6.1.4.1.1466.115.121.1.1
+  USAGE directoryOperation
+)
+</source>
+      <p>
+\\</p>
+      <p>
+\\</p>
+      <p>
+Note that in the above attributetype description for the prescriptiveACI we have
+to include the syntax for ACIItem.  The syntax will need to be added to ApacheDS
+along with the new matching rule directoryStringFirstComponentMatch which is
+defined within section 2.6
+of
+        <a href="http://www.faqs.org/rfcs/rfc3698.html">RFC 3698</a>
+.  Note that RFC 2251 presumes the ACI Item syntax is not human readable.  We
+shall presume that it is human readable.  Here's the JIRA issue and commit
+revision that added these schema objects to the
+server:
+      </p>
+      <p>
+        <a href="http://svn.apache.org/viewcvs.cgi?view=rev&amp;rev=289953">Commit 289953</a>
+      </p>
+      <p>
+        <a href="http://issues.apache.org/jira/browse/DIREVE-257">DIREVE-257</a>
+      </p>
+    </section>
+    <section heading="h2" name="Adding Permission Check Guards to Interceptor Methods">
+      <p>
+To properly check access to an entry we must also check to see if the entry has
+ACIItems associated with it using the entryACI operational attribute.  This
+means for each entry we must check for the presence of this attribute and
+perform checks accordingly.  Entry ACIITems have tuples generated for them and
+those are combined to form s super ACITuple collection.  This collection is fed
+into the ACDF engine to determine if permission is to be
+granted.</p>
+      <p>
+\\</p>
+      <p>
+\\</p>
+      <p>
+Another aspect to this is to determine which grants are required to grant
+permission to an operation.  Unfortunately we loose some resolution regarding
+the correspondance of interceptor operations to protocol operations.  There
+needs to be a way to correlate LDAP protocol operations when interceptor
+operations are invoked so we can make sure the proper permissions are checked
+for.  Presently we have no way to do this.  One thing to research is a means to
+stuff protocol operation information into the environment of each JNDI
+operation.  There has even been some talk about using some sort of session
+object.</p>
+    </section>
+    <section heading="h2" name="UserGroup for ACI evaluation">
+      <p>
+Group membership is included in access control information and is taken into
+account within the ACDF.  The group membership is with respect to the LDAP
+principal the operation is executing as.  This means LDAP principals must either
+track this information or the Authorization subsystem must determine this
+information on the
+fly.</p>
+      <p>
+Question: Should we add group membership information to the LdapPrincipal class
+or should we just let the authorization subsystem track this
+info?</p>
+      <p>
+For the sake of performance it might be best to add group membership information
+to the LdapPrincipal so this information is not looked up every time access
+control decisions need to be made.  Adding the info to the LdapPrincipal however
+will require Authenticator implementations to have to populate this information.
+A base class can automatically populate this information or some utility class
+can also be provided.  Another potential problem is how to update the group
+membership information for LdapPrincipals while they are bound to the directory
+and updates to groups occur.  This however is a problem that can be solved
+later.</p>
+      <p>
+If group membership information is cached and updated within
+the</p>
+      <p>
+authorization module these problems can be minimized.  The interceptor can also
+update membership information as changes occur.  Really there is no other place
+where this info needs to be accessed.  It might not pay to put this fuctionality
+into the LdapPrincipal.  It's cut to have it there but it may not be required
+anywhere but in the authz
+subsystem.</p>
+    </section>
+    <section heading="h2" name="Special User Handling: Administrator">
+      <p>
+It is very easy for users to lock out the administrator from being able to
+access the directory.  This however is not that much of a problem if the access
+control mechanism can be turned off via the configuration.  However note that
+most of the configuration of the server is being pushed back into the DIT
+itself.  This may cause a problem.  In general the administrator of the server
+should have special consideration.  Meaning they should have full access and
+should bypass the access control
+mechanism.</p>
+      <p>
+This is why our implementation will detect this special user and bypass access
+control restrictions.  In effect the admin can perform any
+operation.</p>
+    </section>
+  </body>
+</document>

Added: directory/trunks/apacheds/src/site/xdoc/developers/aci_notesfromx501
URL: http://svn.apache.org/viewcvs/directory/trunks/apacheds/src/site/xdoc/developers/aci_notesfromx501?rev=372968&view=auto
==============================================================================
--- directory/trunks/apacheds/src/site/xdoc/developers/aci_notesfromx501 (added)
+++ directory/trunks/apacheds/src/site/xdoc/developers/aci_notesfromx501 Fri Jan 27 12:11:10 2006
@@ -0,0 +1,166 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<document>
+  <properties>
+    <author email="akarasulu">akarasulu</author>
+    <title>Access Control Notes from X.501</title>
+  </properties>
+  <body>
+    <section heading="h2" name="Access Control Scheme Operational Attribute: accessControlScheme">
+      <p>
+Below is a snipet from X.501 which talks about an accessControlScheme
+attribute:</p>
+      <p>
+The Directory provides a means for the access control scheme in force in a
+particular portion of the DIB to be identified through the use of the
+operational attribute accessControlScheme. The scope of such a scheme is defined
+by an Access Control Specific Area (ACSA), which is a specific administrative
+area that is the responsibility of the corresponding Security Authority. This
+attribute is placed in the Administrative Entry for the corresponding
+Administrative Point. Only administrative entries for Access Control Specific
+Points are allowed to contain an accessControlScheme
+attribute.</p>
+      <p>
+This translates to having an operational attribute, *accessControlScheme*,
+within the entry at the administrative point.  This value of this attribute is
+an OID.  The ASN.1 for the attribute is defined below within section 17.2.2.  We
+specifically need an LDAP attributeType specification for this ASN.1 definition
+for the attribute so we can add it to the Administrative
+Point.</p>
+      <source>accessControlScheme ATTRIBUTE ::= {
+       WITH SYNTAX                                  OBJECT IDENTIFIER
+       EQUALITY MATCHING RULE                       objectIdentifierMatch
+       SINGLE VALUE                                 TRUE
+       USAGE                                        directoryOperation
+       ID                                           id-aca-accessControlScheme }
+</source>
+      <p>
+For basic access control the X.501 attribute will contains the value
+*basic-access-control*.  However for LDAP we can represent the value as
+*basicAccessControl* and assign it an OID to specifically identify this value. 
+Below is the definition for the LDAP
+attributeType:</p>
+      <source>attributetype ( 1.2.6.1.4.1.18060.1.1.1.3.14 NAME 'accessControlScheme'
+  DESC 'Access control scheme in force for a ACSA'
+  EQUALITY objectIdentifierMatch
+  SYNTAX 1.3.6.1.4.1.1466.115.121.1.38
+  USAGE directoryOperation )
+</source>
+    </section>
+    <section heading="h2" name="Protected Items">
+      <table>
+        <tr>
+          <th>
+Protected
+Items</th>
+        </tr>
+        <tr>
+          <td>
+Entries</td>
+        </tr>
+        <tr>
+          <td>
+Attributes</td>
+        </tr>
+        <tr>
+          <td>
+Attribute
+Values</td>
+        </tr>
+        <tr>
+          <td>
+Names</td>
+        </tr>
+      </table>
+    </section>
+    <section heading="h2" name="Aspects of permission categories">
+      <ol nesting="0">
+        <li>
+All operations except delete and modifyDn operations need both entry and
+attribute level
+access.</li>
+        <li>
+To perform Directory operations that require access to attributes or attribute
+values, it is necessary to have entry access permission to the entry or entries
+that contain those attributes or values.  Note the removal of an entry or an
+attribute does not require access to the values of an
+attribute.</li>
+        <li>
+Without an explicit grant access is denied.  Everything is closed from the
+start.  Denials override grants if precedence is the
+same.</li>
+      </ol>
+    </section>
+    <section heading="h2" name="Permission Categories for Entry Access"/>
+    <section heading="h2" name="Subentry Access Control: subentryACI">
+      <p>
+The subentryACI operational attribute would reside within entries of
+administrative points and applies only to immediately subordinate subentries. 
+This is specified within section 18.5.3 of
+X.501.</p>
+      <p>
+Conversely perscriptiveACIs in subentries never apply to subentries of the same
+administrative point however they may apply to the subentries of inner areas. 
+See section 18.5.3 of X.501.  This section is small enough to include
+here:</p>
+      <p>
+Subentry ACI attributes are defined as operational attributes of administrative
+entries, and provide access control information that applies to each of the
+subentries of the corresponding administrative point. Prescriptive ACI within
+the subentries of a particular administrative point never applies to the same or
+any other subentry of that administrative point, but can be applicable to the
+subentries of subordinate administrative points. Subentry ACI attributes are
+contained only in administrative points and do not affect any element of the DIT
+other than immediately subordinate
+subentries.</p>
+      <p>
+In evaluating access control for a specific subentry, the ACI that shall be
+considered
+is:</p>
+      <ul nesting="1">
+        <li>
+the entryACI within the subentry itself (if
+any);</li>
+        <li>
+the subentryACI within the associated administrative entry (if
+any);</li>
+        <li>
+prescriptiveACI associated with other relevant administrative points within the
+same access control specific area (if
+any).</li>
+      </ul>
+      <source>subentryACI  ATTRIBUTE  ::=  { 
+ WITH SYNTAX    ACIItem 
+ EQUALITY MATCHING RULE    directoryStringFirstComponentMatch 
+ USAGE     directoryOperation 
+ ID      id-aca-subentryACI } 
+</source>
+      <p>
+What this means is we have to process access controls differently for
+subentries.  So for a subentry we apply the entryACI as we do with other entry
+types.  Then we need to apply the subentyACI within the parent which is the
+administrative point
+entry.</p>
+      <p>
+Now how we apply perscriptiveACI to subentries is a bit ambiguous.  The subentry
+subsystem does not inject operational attributes into subentries as it does for
+regular entries.  Regular entries included by the subtree specification of
+subentries have the operational attributes associated with administrativeRoles
+added to the included entry.  These opattrs hold a DN to the including subentry.
+This will not occur for entries that are subentries.  At a cursory glance
+imposes some
+problems.</p>
+      <p>
+First of all, we cannot link a subentry A in an outter administrative point to a
+target subentry B included by the subtreeSpecification of the first subentry A. 
+This however may not really be necesary to do.  This is why the X.501 spec is
+somewhat ambiguous when things boil down to an implementation.  Technically a
+subentry is at the same context as its superior administrative point.  If that
+is the case, then all subentries including the administrative point also
+includes the subentries.  Effectively for our implementation, this means that
+subentries can use the accessControlSubentries operational attribute (if
+present) within the administrative entry to discover perscriptiveACI's effecting
+subentries.</p>
+    </section>
+  </body>
+</document>

Added: directory/trunks/apacheds/src/site/xdoc/developers/architecture.xml
URL: http://svn.apache.org/viewcvs/directory/trunks/apacheds/src/site/xdoc/developers/architecture.xml?rev=372968&view=auto
==============================================================================
--- directory/trunks/apacheds/src/site/xdoc/developers/architecture.xml (added)
+++ directory/trunks/apacheds/src/site/xdoc/developers/architecture.xml Fri Jan 27 12:11:10 2006
@@ -0,0 +1,116 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<document>
+  <properties>
+    <author email="akarasulu@apache.org">Alex Karasulu</author>
+    
+  </properties>
+  
+  <body>
+    <section name="High Level Architecture">
+      <subsection name="A picture is worth a thousand words!">
+        <img src="../images/architecture.png"/>
+
+        <p>
+          The server is actually composed of two separable subsystems: the LDAP
+          protocol provider within the SEDA framework and the JNDI provider
+          (a.k.a. the backend subsystem).
+        </p>
+
+        <p>
+          Below we touch breifly on each major subsystem however a more detailed
+          presentation is available describing the server's architecture.  It was an
+          ApacheCon presentation in 04 and is available
+<a href="https://karasulu.homeip.net/svn/akarasulu/apachecon/eve-presentation/eve-intro-long.ppt">here</a>.
+        </p>
+      </subsection>
+
+      <subsection name="LDAP Protocol Provider">
+        <p>
+          The LDAP protocol provider is an implementation of the SEDA protocol
+          provider interface.  SEDA implements a provider architecture where
+          protocols snap into the framework like legos to service protocol
+          requests.  A SEDA provider has no relation to a JNDI provider.  Note
+          it can get confusing when talking about providers for SEDA or for
+          JNDI so we try our best to qualify which we refer to explicitly.
+        </p>
+
+        <p>
+          Other protocol providers may be added to a SEDA instance to service
+          multiple protocols on their respective service ports to share the same
+          plumbing.  In the picture above we show the Kerberos SEDA provider
+          we've implemented along side the LDAP SEDA provider
+        </p>
+
+        <p>
+          The LDAP protocol provider contains request handlers for each LDAP
+          request PDU type.  These handlers translate LDAP requests into
+          operations against an LDAP JNDI provider.  This LDAP JNDI provider by
+          default is the JNDI provider.  However the JNDI provider can be
+          switched using environment properties to use the SUN LDAP JNDI
+          provider.  When using the SUN JNDI Provider the SEDA protocol provider
+          becomes an LDAP proxy server.
+        </p>
+
+        <p>
+          The LDAP protocol provider is extremely simple yet powerful.  It
+          merely acts as an LDAP request PDU to JNDI operation transducer.  On
+          the wire LDAP requests trigger calls against JNDI contexts through
+          handlers.
+        </p>
+      </subsection>
+
+      <subsection name="JNDI Provider">
+        <p>
+          The heart of the server resides within the backend subsystem or the
+          JNDI provider.  The JNDI provider is a JNDI provider for the
+          LDAP namespace.  However this provider does not talk LDAP on the wire,
+          it effects the internal backing stores of the server directly.  Hence
+          the JNDI Provider is really the server side JNDI provider.
+        </p>
+
+        <p>
+          Fundamentally JNDI is used as the facade to the entire backend
+          subsystem.  JNDI interfaces are used to operated upon server backing
+          stores this way.  JNDI also serves as the integration API for
+          embedding the server.  The ServerContextFactory starts up the backend
+          subsystem as well as the networking code when the first initial
+          context is requested.  All other contexts do not incur startup costs.
+          This unique use of JNDI enables code to simply switch JNDI providers
+          to embed the server.  It also makes data access code in stored
+          procedures that uses JNDI capable of running inside and outside of
+          the server which makes testing really easy.
+        </p>
+
+        <p>
+          The directory server's backend subsystem contains most of the guts of
+          the server.  We want functionality like replication or triggers to be
+          present there regardless of whether the server is in standalone mode
+          or embedded within another application.  Hence keeping it within the
+          backend made sense.
+        </p>
+
+        <p>
+          The server contains backing stores to store LDAP entries which really
+          are serialized javax.naming.directory.Attributes objects.  These
+          entries live within database partitions attached to a naming context.
+          All entries within these contexts are contained within the partition
+          assigned to it.  Several partitions can be present within the same
+          directory server instance.  Operations against contexts are routed by
+          a Nexus based on the name (DN) of the entry associated with the
+          operation.
+        </p>
+
+        <p>
+          JNDI contexts hence translate relative operations to distinguished
+          operations against the Nexus which routes these calls to the
+          respective partition to add, delete, modify, search or move around
+          entries.  Between calls from JNDI Contexts to the RootNexus an
+          interceptor framework intervenes to inject services like replication,
+          authorization and more.
+        </p>
+      </subsection>
+
+    </section>
+
+  </body>
+</document>

Added: directory/trunks/apacheds/src/site/xdoc/developers/backend.xml
URL: http://svn.apache.org/viewcvs/directory/trunks/apacheds/src/site/xdoc/developers/backend.xml?rev=372968&view=auto
==============================================================================
--- directory/trunks/apacheds/src/site/xdoc/developers/backend.xml (added)
+++ directory/trunks/apacheds/src/site/xdoc/developers/backend.xml Fri Jan 27 12:11:10 2006
@@ -0,0 +1,120 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<document>
+  <properties>
+    <author email="akarasulu@apache.org">Alex Karasulu</author>
+    
+  </properties>
+  
+  <body>
+    <section name="Backend Subsystem">
+      <p>
+        The backend subsystem is everything minus the networking layer and the
+        protocol handling layer.  It is composed of several parts in itself: the
+        JNDI provider, interceptor framework, schema subsystem, and database
+        subsystem.  Each sub-subsystem of the backend is described in the
+        sections to follow.
+      </p>
+
+
+      <subsection name="Database Subsystem">
+        <p>
+          The overall design to the database subsystem is described to some
+          degree within the partition documentation which can be found
+          <a href="../users/partition.html">here</a>.  In summary this subsystem
+          is responsible for storing and accessing entries addressed by DN.
+        </p>
+
+        <p>
+          Eventually we intend to delve into the design of the database
+          subsystem by breaking down the search engine, optimizer and default
+          backing store design which uses JDBM BTrees.
+        </p>
+
+        <p>
+          For future reference below the RootNexus is the top level object or
+          facade of the database subsystem.  It contains all context partitions
+          and routes calls to them based on the location of the context within
+          the namespace.
+        </p>
+      </subsection>
+
+
+      <subsection name="JNDI Provider">
+        <p>
+          The JNDI Provider is just an implementation of the
+          InitialContextFactory, Context, and other derived interfaces.  The
+          factory is used to fire up the entire server if it has not been
+          started already to service the JNDI request.  The contexts are simple
+          wrappers around the database subsystem which point to a specific entry
+          withing the namespace.  More will be put here as time progresses ...
+        </p>
+      </subsection>
+
+
+      <subsection name="Interceptor Framework">
+        <p>
+          Calls to the RootNexus are made from within Context implementations
+          of the JNDI provider.  Relative Context positions or names are
+          translated into (absolute) distinguished names and the appropriate
+          call is made on the RootNexus.  The calls are intercepted using a
+          proxy and additional functionality is injected before, after and on
+          exception to calls made on the RootNexus.
+        </p>
+
+        <p>
+          A framework is built around this.  The Context, parameters, return
+          values and any exceptions that may be thrown by the call are
+          encapsulated within an Invocation object.  This object is passed to
+          a chain of interceptors that operate on the values it holds to
+          implement a service.
+        </p>
+
+        <p>
+          There are three separate types or stages of interceptors.
+          Interceptors can operate before a method invocation, after an
+          invocation and when an error results during any point in this process.
+          Separate chains of interceptors have been created for each stage.  The
+          Invocation object is passed through this chain and each interceptor
+          operates upon it.
+        </p>
+
+        <p>
+          Not all interceptor chains are created equally!  The before and after
+          chains are fail fast.  Meaning the processing of an Invocation object
+          shorts the rest of the chain if one interceptor fails while processing
+          the invocation.  This is not the case when processing exceptions in
+          the on error interceptor chain.  Regardless of an interceptor's
+          success downstream, all interceptors are guaranteed a chance to
+          operate on the Invocation object.  This makes the on-error chain an
+          excellent place to put cleanup code or code to handle failures.
+        </p>
+
+        <p>
+          When implementing a cross cutting service with the interceptor
+          framework one or more interceptors may be added to one or more
+          chains.  Keep in mind this framework helps inject new functionality
+          but it can get conjested very quickly.
+        </p>
+      </subsection>
+
+
+      <subsection name="Schema Subsystem">
+        <p>
+          The schema subsystem manages LDAP schema objects.  These objects
+          have a direct effect on how lookups and search operations are
+          conducted on the directory.  The subsystem contains a set of
+          registries for each type of LDAP schema object based on OID.
+        </p>
+
+        <p>
+          Schema objects may reference one another by OID and so the system
+          is designed to dynamically resolve dependent objects by lookups on
+          these registries.
+        </p>
+      </subsection>
+
+
+    </section>
+
+  </body>
+</document>

Added: directory/trunks/apacheds/src/site/xdoc/developers/components.xml
URL: http://svn.apache.org/viewcvs/directory/trunks/apacheds/src/site/xdoc/developers/components.xml?rev=372968&view=auto
==============================================================================
--- directory/trunks/apacheds/src/site/xdoc/developers/components.xml (added)
+++ directory/trunks/apacheds/src/site/xdoc/developers/components.xml Fri Jan 27 12:11:10 2006
@@ -0,0 +1,153 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<document>
+  <properties>
+    <author email="akarasulu@apache.org">Alex Karasulu</author>
+    
+  </properties>
+  
+  <body>
+    <section name="Resources">
+        <p>
+          If the following sections sound a little cryptic you might want 
+          to read a little about the IoC pattern. Below are some documents you
+          might find useful when translating some of this babble:
+        </p>
+        
+        <ul>
+          <li><a href="http://wiki.apache.org/avalon/WhatIsIoC">
+          Inversion of Control Pattern</a></li>
+          
+          <li><a href="http://wiki.apache.org/avalon/AvalonNoLogging?highlight=%28NoLogging%29">
+             Paul Hammant's use of Monitors instead of Loggers</a> is a technique we use.
+          </li>
+        </ul>
+    </section>
+    
+    <section name="Components and Services">
+      <p>
+        The server is designed as a system of highly granular components.
+        Some components are a collection of other components with a facade to 
+        form a subsystem of the server.  Subsystems can contain other 
+        subsystems and one component can depend on zero or more other
+        components.
+      </p>
+      
+      <p>
+        A micro kernel or component container is required to run the server.  By
+        default the server uses its oun glue rather than a container with all the
+        bells and whistles.  However it can run in any micro kernel using
+        service wrappers.  A micro kernel is a peice of code operating as a
+        component container providing services for that component and running
+        the component through a set of life-cycles.  The server is designed to run
+        on any micro kernel using component wrappers.  The subsystems and
+        components are designed as Plain Old Java Interfaces and Objects (POJIs
+        and POJOs) that can be wrapped to make them interoperate within
+        different containers.
+      </p>
+      
+      <p>
+        Each component within the server has a public service interface which
+        declares what that component can do for its clients.  It is always good
+        to keep the interfaces separate from any specific implementations.  You
+        can have many implementations for the same service interface.  Secondly
+        the classloader heirarchy in containers often puts implementation
+        classloaders under a classloader containing the service interface. 
+        This allows containers to manage multiple implementations for the
+        same service without having conflicts.  Also implementations can be
+        created and destroyed in separate classloaders without affecting one
+        another.
+      </p>
+    </section>
+    
+    <section name="Container Independence">
+      <p>
+        One of the biggest impediments we've had to deal with while developing
+        the server and its precursors was having containers go in and out of
+        fashion.  We lost several months of development time while switching
+        from Pheonix to Merlin for example.  Today we use some custom glue
+        instead.
+      </p>
+      
+      <p>
+        The server has been designed this time from the ground up to be
+        independent of any container.  We are doing this by making the default
+        implementation of a service a Plain Old Java Object (POJO).  Wrapper
+        implementation projects, one for each supported container, are used to
+        wrap these POJO components to introduce container specific lifecycles
+        and to encapsulate container idiosyncrasies.
+      </p>
+      
+      <p>
+        This approach we have found has several advantagous side-effects.  One 
+        benefit was a nice separation of concerns.  By separating out the 
+        container specific code, configuration and build aspects, developers
+        no longer need to be aware of container details.  They can focus on the
+        core implemenation as a simple class implementing an interface.  Those
+        interested in making the server run in one container as opposed to
+        another can focus on their container wrapper without the clutter of
+        another container getting in the way.  This reduces the complexity and
+        learning curve for all those involved in developing the directory
+        server's components and subsystems.
+      </p>
+    </section>
+    
+    <section name="Monitors Verse Loggers">
+      <p>
+        Above we provided a link to Paul Hammant's concept of using Monitors
+        in place of Logging.  Briefly without restating his wiki we'd like to
+        review how we use Monitors instead of Loggers alone.
+      </p>
+      
+      <p>
+        Like any other server we need to log what goes on.  But rather than log
+        we need to monitor.  Logging is a specific type of monitoring for the 
+        sake of archiving what we monitor.  Paul proposed that every service
+        should propose a very specific Monitor interface.  This is a good idea 
+        because it is the responsibility of the service to announce those 
+        interesting, and monitoring worthy events.  The interface forces 
+        signatures to explicitly describe what information is involved in the
+        monitoring of an event.
+      </p>
+      
+      <p>
+        This makes the component implementation logging system independent
+        which is provided by a container implementation.  Each wrapper
+        implementation can provide its own Monitor implementation
+        to interface with the Logging system of the target container.
+      </p>
+      
+      <p>
+        We gain by becoming more container independent but more importantly we
+        are forced to consider what events in a service constitutes a
+        noteworthy event.  This throught provoking aspect is perhaps the most
+        beneficial.
+      </p>
+    </section>
+    
+    <section name="Configuration Beans">
+      <p>
+        Containers are neat because they give component developers a lot of 
+        nice features out of the box and that's what they should do.  The key
+        to maintaining container independence is to abstract away from these
+        features while still taking advantage of them.  This usually translates
+        into a few extra interfaces and classes.
+      </p>
+      
+      <p>
+        One benefit of containers is to provide a means to associate a 
+        configuration with a component.  Most allow for configurations to be 
+        stored in properties files and/or XML files.  Containers read and load
+        the configuration as a part of processing the lifecycles of components.
+      </p>
+      
+      <p>
+        Rather than have POJO component implementations depend directly on 
+        configuration interfaces specific to a container we explicitly define
+        configuration beans.  POJO implementations are then designed to take 
+        configuration beans as constructor arguments if the number of parameters
+        is large and putting so many parameters into a constructor would be
+        too cumbersome.
+      </p>
+    </section>
+  </body>
+</document>
\ No newline at end of file

Added: directory/trunks/apacheds/src/site/xdoc/developers/index.xml
URL: http://svn.apache.org/viewcvs/directory/trunks/apacheds/src/site/xdoc/developers/index.xml?rev=372968&view=auto
==============================================================================
--- directory/trunks/apacheds/src/site/xdoc/developers/index.xml (added)
+++ directory/trunks/apacheds/src/site/xdoc/developers/index.xml Fri Jan 27 12:11:10 2006
@@ -0,0 +1,78 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<document>
+  <properties>
+    <author email="akarasulu@apache.org">Alex Karasulu</author>
+    
+  </properties>
+  
+  <body>
+    <section name="Developer's Guide">
+      <p>
+      </p>
+      
+      <table>
+        <tr>
+          <th>Topic</th>
+          <th>Description</th>
+        </tr>
+        
+        <tr>
+          <td>
+            <a href="./architecture.html">Architecture</a>
+          </td>
+          <td>
+            The server's high level architecture.
+          </td>
+        </tr>
+
+        <tr>
+          <td>
+            <a href="./components.html">Components</a>
+          </td>
+          <td>
+            How we do components in the directory server.
+          </td>
+        </tr>
+
+        <tr>
+          <td>
+            <a href="./networking.html">Networking</a>
+          </td>
+          <td>
+            Describes the directory servers's networking code.
+          </td>
+        </tr>
+
+        <tr>
+          <td>
+            <a href="./protocol.html">Protocol</a>
+          </td>
+          <td>
+            The design of LDAP protocol layer.
+          </td>
+        </tr>
+
+        <tr>
+          <td>
+            <a href="./backend.html">Backend Subsystem</a>
+          </td>
+          <td>
+            Looks at the backend subsystem design in detail.
+          </td>
+        </tr>
+
+        <tr>
+          <td>
+            <a href="./.html"></a>
+          </td>
+          <td>
+
+          </td>
+        </tr>
+
+      </table>
+
+
+    </section>
+  </body>
+</document>

Added: directory/trunks/apacheds/src/site/xdoc/developers/interceptor_interactions.xml
URL: http://svn.apache.org/viewcvs/directory/trunks/apacheds/src/site/xdoc/developers/interceptor_interactions.xml?rev=372968&view=auto
==============================================================================
--- directory/trunks/apacheds/src/site/xdoc/developers/interceptor_interactions.xml (added)
+++ directory/trunks/apacheds/src/site/xdoc/developers/interceptor_interactions.xml Fri Jan 27 12:11:10 2006
@@ -0,0 +1,164 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<document>
+  <properties>
+    <author email="akarasulu">akarasulu</author>
+    
+  </properties>
+  <body>
+    <p>
+Interceptors will perform operations on behalf of the user/context making calls
+against the proxy.  Interceptors will often need to access or alter the DIT. 
+Interceptors have several options for DIT
+access/alteration.</p>
+    <ol nesting="0">
+      <li>
+operate directly against the
+nexus</li>
+      <li>
+operate against the nexus
+proxy</li>
+      <li>
+operate against the next Interceptor in the
+chain</li>
+      <li>
+operate against JNDI
+interfaces</li>
+      <li>
+operate against the nexus proxy with selective
+bypass</li>
+      <li>
+out of band support methods on
+Interceptors</li>
+    </ol>
+    <p>
+A combination of these approaches can be taken.  Each one has side effects and
+ramifications when used.  We will discuss the ramifications of each option as it
+relates to Interceptor interactions.  Interceptor interactions (coupling)
+undermine the overall goal of having orthogonal independent
+services.</p>
+    <section heading="h2" name="Direct Operations Against the Nexus">
+      <p>
+Direct operations against the system nexus retrieves or alters raw entries
+stored within partitions.  Sometimes this is absolutely necessary and sometimes
+it could lead to serious
+problems.</p>
+      <subsection heading="h3" name="Direct operations on the nexus bypass the Interceptor Mechanism">
+        <p>
+Direct operations on the nexus bypass the Interceptor mechanism.  No Invocation
+object is pushed onto the InvocationStack, and no Interceptors intercept the
+call.  If the Interceptor code calling the nexus relies on pre or post
+processing by any other Interceptor there will be a
+problem.</p>
+        <p>
+A good example is the reliance of upstream Interceptors on the Mitosis
+replication Interceptor.  Upstream Interceptors ironically don't even know of
+the presence of the Mitosis Interceptor, nor that they rely on it.  Mitosis does
+not actually delete entries but marks them deleted.  The Mitosis Interceptor
+filters out deleted entries from searches and responds according with
+NameNotFoundExceptions when other operations are performed on entries marked for
+deletion.  Interceptors before the Mitosis Interceptor don't have to worry about
+whether or not an entry is deleted because this is handled already.  This is not
+the case for downstream Interceptors so positioning is critical.  Direct access
+to the nexus however bypasses the Mitosis Interceptor along with all others and
+makes deleted entries
+reappear.</p>
+      </subsection>
+      <subsection heading="h3" name="Raw access to partition entries may be required">
+        <p>
+Raw access to partition entries should be done with extreme caution.  But at
+times this access may be absolutely necessary.  The Interceptor, it's position
+and the effects of bypassing other possibly unknown Interceptors must be taking
+into
+consideration.</p>
+      </subsection>
+    </section>
+    <section heading="h2" name="Operations on the Nexus Proxy">
+      <p>
+Interceptors that have intercepted an operation, may use the proxy to perform
+other operations.  These other operations performed to satisfy the first
+intercepted operation will also traverse the
+InterceptorChain.</p>
+      <subsection heading="h3" name="There is a risk for infinate recursion">
+        <p>
+The danger here is an infinite recursion.  Let's suppose the first intercepted
+operation, Invocation *A*, performs operations *A'* (that's A prime) and *B*
+against the nexus.  Invocation *A'* by the way is the same operation as the
+intercepted operation but with different parameters. The same operation does not
+mean the same Invocation.  In this case *A'* may incur another set of Invocation
+*A"* and *B'* all invoked within the same Interceptor.  This chain reaction
+could continue unabated to blow out the stack without
+regulation.</p>
+        <p>
+A good example of an Interceptor prone to an infinite recursion is the
+AuthorizationService.  It needs to lookup and search for other other entries to
+determine access rights to perform operations.  Those lookup and search
+operations in turn trigger the AuthorizationService again to issue another set
+of lookup and search operations and so on.  An infinate recursion is the
+result.</p>
+        <p>
+If the AuthorizationService could call lookup and search on the nexus proxy
+while bypassing itself then the recursion can be avoided.  This raises the
+question of whether or not sub-operations excecuted by Interceptors are really
+considered to be performed by the user of the intercepted
+call.</p>
+      </subsection>
+      <subsection heading="h3" name="Effects on the InvocationStack">
+        <p>
+Calls against the nexus proxy are not presently possible.  They can however be
+enabled.  The foreseeable mechanism would be to just call the proxy object of
+the current intercepted operation.  This could be done by peeking at the
+InvocationStack to get a handle on the Invocation object for the current
+operation.  From there the calling Context can be accessed.  An accessor in the
+Context implementation can expose access to the nexus proxy
+object.</p>
+        <p>
+Calling this nexus proxy will push a new Invocation object on top of the current
+operation's Invocation object.  This is good  even though the Context is used to
+issue yet another Invocation.  The key advantage though is that we can
+diffentiate between the two Invocations even if the caller Context, operation
+and the parameters are the
+same.</p>
+      </subsection>
+      <subsection heading="h3" name="Identity Lock-in">
+        <p>
+Because the same Context object is used, the identity performing the operation
+is the same.  This may be good and
+bad.</p>
+        <p>
+It's good because we are associating the sub-operations with the user performing
+the primary operation.  Although if we peek onto the stack the bottom most
+Invocation tells us who the original Invocation was issued by.  Even if
+sub-operations are performed as another user like the super-user we can tell who
+the original user was that this sub-operation was issued on behalf
+of.</p>
+        <p>
+There will be situations when we want a setUid like mechanism to access
+protected information on behalf of the current user.  Even if the current user
+does not have access to protected resources, the Interceptor should be able to
+access these resources to satisfy the current intercepted operation.  Meaning
+the Interceptor will need to perform operations as if it were the admin user to
+satisfy an operation on behalf of the current user.  Doing this is no simple
+matter: authentication must be bypassed to enable an operation as the admin
+user.  Otherwise we would need access to the admin's credentials.  Plus
+re-authentication as the admin is unnecesary since the Interceptor is trusted
+with admin rights.  If we trust the Interceptor and give it the ability to
+access the DIT as the admin, we must be sure this is done without compromising
+security.</p>
+        <p>
+Another alternative to access protected resources would be to disable access
+controls for select sub-operations performed by an Interceptor.  Perhaps even if
+an operation's associated identity is unchanged, another parameter can be used
+to provide access as another user.  This would be a special cue to the
+Authorization
+subsystem.</p>
+        <p>
+These limitations just show us that we're missing something in the design of the
+Interceptor Mechanism.  Whether we need to handle sub-operations with special
+authorization measures, selectively bypass or require specific Interceptors
+something is
+required.</p>
+      </subsection>
+    </section>
+  </body>
+</document>

Added: directory/trunks/apacheds/src/site/xdoc/developers/interceptor_mechanism.xml
URL: http://svn.apache.org/viewcvs/directory/trunks/apacheds/src/site/xdoc/developers/interceptor_mechanism.xml?rev=372968&view=auto
==============================================================================
--- directory/trunks/apacheds/src/site/xdoc/developers/interceptor_mechanism.xml (added)
+++ directory/trunks/apacheds/src/site/xdoc/developers/interceptor_mechanism.xml Fri Jan 27 12:11:10 2006
@@ -0,0 +1,115 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<document>
+  <properties>
+    <author email="akarasulu">akarasulu</author>
+    
+  </properties>
+  <body>
+    <section heading="h2" name="What is it?">
+      <p>
+The mechanism is a means for injecting and isolating orthogonal services into
+calls against the nexus.  The nexus is the hub used to route calls to partitions
+to perform CRUD operations upon entries.  By injecting these services at this
+level, partition implementators need not duplicate fuctionality.  Services such
+as authentication, authorization, schema checking, normalization, operational
+attribute maintenance and more are introduced using Interceptors.  By using
+interceptors partition implementors need not be concerned with these aspects and
+can focus on raw CRUD operations against their backing stores what ever they may
+be.</p>
+    </section>
+    <section heading="h2" name="How does it work?">
+      <p>
+Before we talk more about interceptors we must quickly cover the JNDI provider
+implementation since it is somewhat
+related.</p>
+      <subsection heading="h3" name="JNDI Implementation">
+        <p>
+The JNDI implementation is composed of a set of JNDI Context implementations, a
+ContextFactory implementation and a set of helper
+classes.</p>
+        <ul nesting="1">
+          <li>
+DeadContext</li>
+          <li>
+JavaLdapSupport</li>
+          <li>
+ServerContext</li>
+          <li>
+ServerDirContext</li>
+          <li>
+ServerLdapContext</li>
+          <li>
+AbstractContextFactory</li>
+          <li>
+CoreContextFactory</li>
+          <li>
+ServerDirObjectFactory</li>
+          <li>
+ServerDirStateFactory</li>
+        </ul>
+        <p>
+Every JNDI Context implementation in the provider holds a dedicated reference to
+a nexus proxy object.  This proxy contains all the operations that the nexus
+contains.  The proxy  object is at the heart of the mechanism.  We will disuss
+it more after covering the rest of the JNDI
+provider.</p>
+        <p>
+Calls made against JNDI Contexts take relative names as arguments.  These names
+are relative to the distinguished name of the JNDI Context.  Within the Context
+implementations these relative names are transformed into absolute distinguished
+names.  The transformed names are used to make calls against the
+proxy.</p>
+        <p>
+Additional processing may occur before or after a call is made by a context on
+its proxy to manage JNDI provider specific functions.  One such example is the
+handling of Java objects for serialization and the use of object and state
+factories.</p>
+      </subsection>
+      <subsection heading="h3" name="The nexus proxy object">
+        <p>
+As mentioned above, each Context that is created has a nexus proxy.  The proxy
+maintains a handle on the context as
+well.</p>
+        <p>
+The primary job of the proxy is to inject Interceptor based services.  It does
+so by invoking a chain of Interceptors managed by the system.  Interceptors
+mirror the methods that are intercepted on the nexus interface.  When an
+intercepted method is invoked on the proxy, the proxy pushes an Invocation
+object on to the InvocationStack associated with the current executing Thread. 
+The proxy then calls the same method on a chain of Interceptors.  The results of
+the call are returned after the InvocationStack is
+popped.</p>
+        <p>
+The InvocationStack is used to track the calls being intercepted.  Invocation
+objects pushed onto the stack track the context making the call to the proxy,
+the name of the intercepted call and its arguments.  A stack is used because in
+the case of Triggers, stored procedures may be invoked which operate against the
+DIT using JNDI.  These JNDI calls will also be intercepted.  Their Invocation
+object will be stacked on top of the Invocation which raised the Trigger.  This
+way identities and context of operations can be tracked and used by the Trigger
+management system to prevent runnaway cascades or to limit the cascade depth. 
+There are other areas besides just triggers where this stack will serve a
+purpose.</p>
+        <p>
+The InterceptorChain is a container of Interceptors which has the same or
+analogous methods as do Interceptors.  These are for the interceptable methods. 
+A call against the chain invokes the first Interceptor which then usually
+invokes the next interceptor in the chain.  An Interceptor need not call the
+next interceptor however.  It can raise an exception before making the call to
+the next interceptor or it can completely bypass the rest of the chain by just
+returning before calling the next Interceptor.  Interceptors can preprocess the
+arguments, or perform other tasks before they invoke the next Interceptor.  They
+can also catch exceptions raised by other downstream interceptors and respond to
+them to handle errors.  Finally they can perform post processing operations on
+the results of returned values from downstream
+Interceptors.</p>
+        <p>
+One might ask when is the call made against the actual nexus.  This happens
+using a special Interceptor which resides at the end of the chain.  It actually
+makes the call against the nexus and returns the
+results.</p>
+      </subsection>
+    </section>
+  </body>
+</document>

Added: directory/trunks/apacheds/src/site/xdoc/developers/networking.xml
URL: http://svn.apache.org/viewcvs/directory/trunks/apacheds/src/site/xdoc/developers/networking.xml?rev=372968&view=auto
==============================================================================
--- directory/trunks/apacheds/src/site/xdoc/developers/networking.xml (added)
+++ directory/trunks/apacheds/src/site/xdoc/developers/networking.xml Fri Jan 27 12:11:10 2006
@@ -0,0 +1,64 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<document>
+  <properties>
+    <author email="akarasulu@apache.org">Alex Karasulu</author>
+    
+  </properties>
+  
+  <body>
+    <section name="Networking">
+      <p>
+        We wanted to keep the networking code as independent as possible to
+        prevent it's concerns from creeping into the LDAP protocol handling
+        code.  Furthermore we wanted it to be independent of the LDAP protocol
+        so it can be reused as much as possible with other protocols.
+      </p>
+
+      <p>
+        This lead to the creation of a newtorking framework or two.  These
+        frameworks use different approaches and models to provide the network
+        plumbing needed by internet protocol servers.  A common protocol
+        provider API is used to implement protocols enabling the provider on
+        all network frameworks.
+      </p>
+
+      <p>
+        Each network framework at the directory project has its own project so
+        its best to delegate a description of each framework to the appropriate
+        project documentation:
+      </p>
+
+      <table>
+        <tr>
+          <th>Framework</th>  <th>Description</th>
+        </tr>
+
+        <tr>
+          <td><a href="../../seda/index.html">seda</a></td>
+
+          <td>
+            A simple framework for implementing staged event driven internet
+            protocol servers.
+          </td>
+        </tr>
+
+        <tr>
+          <td><a href="../../seda/index.html">sedang</a></td>
+
+          <td>
+            The next generation seda framework based on d-haven event packages.
+          </td>
+        </tr>
+
+        <tr>
+          <td><a href="../../mina/index.html">mina</a></td>
+
+          <td>
+            Multipurpose Infrastrusture for Network Applications based on ACE.
+          </td>
+        </tr>
+      </table>
+    </section>
+
+  </body>
+</document>

Added: directory/trunks/apacheds/src/site/xdoc/developers/partitions.xml
URL: http://svn.apache.org/viewcvs/directory/trunks/apacheds/src/site/xdoc/developers/partitions.xml?rev=372968&view=auto
==============================================================================
--- directory/trunks/apacheds/src/site/xdoc/developers/partitions.xml (added)
+++ directory/trunks/apacheds/src/site/xdoc/developers/partitions.xml Fri Jan 27 12:11:10 2006
@@ -0,0 +1,21 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<document>
+  <properties>
+    <author email="akarasulu@apache.org">Alex Karasulu</author>
+    
+  </properties>
+  
+  <body>
+    <section name="Default Partition Design">
+    </section>
+
+    <section name="How does alias dereferencing while searching work?">
+      <p>You're going to want to read these documents here:</p>
+
+      <ul>
+        <li><a href="./xldbm.pdf">Paper LDAP database design by Tim Howes</a></li>
+        <li><a href="./alias-dereferencing.pdf">Paper on alias dereferencing mechanism by Alex Karasulu</a></li>
+      </ul>
+    </section>
+  </body>
+</document>



Mime
View raw message