Mailing-List: contact commits-help@directory.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@directory.apache.org
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Subject: svn commit: r1423751 - in
 /directory/site/trunk/content/apacheds/advanced-ug: 2-server-config.mdtext
 3-admin-model.mdtext 3.1-administrative-points.mdtext
 3.2-operations-on-an-administrativepoint.mdtext
Date: Wed, 19 Dec 2012 03:34:02 -0000
To: commits@directory.apache.org
From: antoine@apache.org
Message-Id: <20121219033402.7D1FD23888CD@eris.apache.org>

Author: antoine
Date: Wed Dec 19 03:34:01 2012
New Revision: 1423751

URL: http://svn.apache.org/viewvc?rev=1423751&view=rev
Log:
adding 3.2-operations-on-an-administrative point

Added:
    directory/site/trunk/content/apacheds/advanced-ug/3.2-operations-on-an-administrativepoint.mdtext
Modified:
    directory/site/trunk/content/apacheds/advanced-ug/2-server-config.mdtext
    directory/site/trunk/content/apacheds/advanced-ug/3-admin-model.mdtext
    directory/site/trunk/content/apacheds/advanced-ug/3.1-administrative-points.mdtext

Modified: directory/site/trunk/content/apacheds/advanced-ug/2-server-config.mdtext
URL: http://svn.apache.org/viewvc/directory/site/trunk/content/apacheds/advanced-ug/2-server-config.mdtext?rev=1423751&r1=1423750&r2=1423751&view=diff
==============================================================================
--- directory/site/trunk/content/apacheds/advanced-ug/2-server-config.mdtext (original)
+++ directory/site/trunk/content/apacheds/advanced-ug/2-server-config.mdtext Wed Dec 19 03:34:01 2012
@@ -4,7 +4,7 @@ NavPrevText: 1 - Architecture
 NavUp: ../advanced-users-guide.html
 NavUpText: Advanced User Guide
 NavNext: 3-admin-model.html
-NavNextText: 4 - Administrative Model
+NavNextText: 3 - Administrative Model
 Notice: Licensed to the Apache Software Foundation (ASF) under one
     or more contributor license agreements.  See the NOTICE file
     distributed with this work for additional information

Modified: directory/site/trunk/content/apacheds/advanced-ug/3-admin-model.mdtext
URL: http://svn.apache.org/viewvc/directory/site/trunk/content/apacheds/advanced-ug/3-admin-model.mdtext?rev=1423751&r1=1423750&r2=1423751&view=diff
==============================================================================
--- directory/site/trunk/content/apacheds/advanced-ug/3-admin-model.mdtext (original)
+++ directory/site/trunk/content/apacheds/advanced-ug/3-admin-model.mdtext Wed Dec 19 03:34:01 2012
@@ -89,4 +89,5 @@ Those missing parts will be implemented 
 ## Chapter content
 
 * [3.1 - Administrative Points](3.1-administrative-points.html)
+* [3.2 - Operations on an Administrative Point](3.2-operations-on-an-administrativepoint.html)
 

Modified: directory/site/trunk/content/apacheds/advanced-ug/3.1-administrative-points.mdtext
URL: http://svn.apache.org/viewvc/directory/site/trunk/content/apacheds/advanced-ug/3.1-administrative-points.mdtext?rev=1423751&r1=1423750&r2=1423751&view=diff
==============================================================================
--- directory/site/trunk/content/apacheds/advanced-ug/3.1-administrative-points.mdtext (original)
+++ directory/site/trunk/content/apacheds/advanced-ug/3.1-administrative-points.mdtext Wed Dec 19 03:34:01 2012
@@ -1,10 +1,10 @@
 Title: 3.1. Administrative points
 NavPrev: 3-admin-model.html
 NavPrevText: 3 - Administrative Model
-NavUp: ../3-admin-model.html
-NavUpText: Administrative Model
-NavNext: 4-.html
-NavNextText: 4 -
+NavUp: 3-admin-model.html
+NavUpText: 3 - Administrative Model
+NavNext: 3.2-operations-on-an-administrativepoint.html
+NavNextText: 3.2 Operations on an a Administrative Point
 Notice: Licensed to the Apache Software Foundation (ASF) under one
     or more contributor license agreements.  See the NOTICE file
     distributed with this work for additional information
@@ -22,7 +22,6 @@ Notice: Licensed to the Apache Software 
     specific language governing permissions and limitations
     under the License.
 
-<a name="3.1.Administrativepoints-Introduction"></a>
 # Introduction
 
 An *Administrative Point* is an entry which is defining a starting point
@@ -53,7 +52,6 @@ The schema shows the relation between th
 ![subentry](images/subentry.png)
 
 
-<a name="3.1.Administrativepoints-AdministrativePoint"></a>
 ## Administrative Point
 We will describe the types of Administrative Points we are managing and the
 way they impact their associated Administrative Areas (*AA*)
@@ -79,7 +77,6 @@ but the one covered by the new *SAP*)
 or *IAP*. It controls a specific aspect too, as for the *SAP*, but it will
 be combined with any of the above *AP*.
 
-<a name="3.1.Administrativepoints-Roles"></a>
 ## Roles
 *AP* are managing some administrative aspect, defined by a role :
 * ACI : Manage the access control
@@ -87,7 +84,6 @@ be combined with any of the above *AP*.
 * SubSchema (not handled atm) 
 * TriggrExecution : Manage the execution of stored procedures
 
-<a name="3.1.Administrativepoints-Subentry"></a>
 # Subentry
 
 Once we have defined an *AP*, we can add some *subentries* which contain

Added: directory/site/trunk/content/apacheds/advanced-ug/3.2-operations-on-an-administrativepoint.mdtext
URL: http://svn.apache.org/viewvc/directory/site/trunk/content/apacheds/advanced-ug/3.2-operations-on-an-administrativepoint.mdtext?rev=1423751&view=auto
==============================================================================
--- directory/site/trunk/content/apacheds/advanced-ug/3.2-operations-on-an-administrativepoint.mdtext (added)
+++ directory/site/trunk/content/apacheds/advanced-ug/3.2-operations-on-an-administrativepoint.mdtext Wed Dec 19 03:34:01 2012
@@ -0,0 +1,183 @@
+Title: 3.2 Operations on an Administrative Point
+NavPrev: 3.1-administrative-points.html
+NavPrevText: 3.1 - Administrative Points
+NavUp: ../3-admin-model.html
+NavUpText: Administrative Model
+NavNext: 4-.html
+NavNextText: 4 -
+Notice: Licensed to the Apache Software Foundation (ASF) under one
+    or more contributor license agreements.  See the NOTICE file
+    distributed with this work for additional information
+    regarding copyright ownership.  The ASF licenses this file
+    to you under the Apache License, Version 2.0 (the
+    "License"); you may not use this file except in compliance
+    with the License.  You may obtain a copy of the License at
+    .
+    http://www.apache.org/licenses/LICENSE-2.0
+    .
+    Unless required by applicable law or agreed to in writing,
+    software distributed under the License is distributed on an
+    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+    KIND, either express or implied.  See the License for the
+    specific language governing permissions and limitations
+    under the License.
+
+# Operations
+There are six kind of operations we can have on an AdministrativePoint :
+- creating a new AP
+- removing an existing AP
+- modifying an existing AP by adding or removing a role
+- renaming an AP
+- moving an AP
+- renaming or moving an AP
+
+Renaming an AP has no impact on the administrative model, as we don't point
+(internally) on the entry's DN, but on its UUID, so the last three
+operations can be gathered into one single Move operation.
+
+Also note that any modification made on an entry's AdminsitrativeRole may
+have an impact on all it's descendants and ascendants (this is true for the
+Modify and Move operation)
+
+## Adding an AP entry
+This seems to be a simple operation, however many checks have to be done in
+order to not break the existing Administrative model. 
+
+First of all, we have to check that the added entry contains the
+AdministrativeRole attributeType, and that this role is not empty. As we
+don't have any semantic control for this AT (the attached syntax is just
+expecting the values to be Strings), we have to do those checks in the
+AdminInterceptor.
+
+Here are the checks we must provide :
+* the AdministrativeRole AT must have values
+* those values must be roles (ie one of the 4 possible specific area roles,
+or one of the 3 inner area roles, or the autonomous area role)
+* there should not be duplicated
+* we can't have an AAP with any other role
+* we can't have an IAP and an SAP for the same role
+
+Once those basic checks done, we also have to check that the roles
+hierarchy will remain consistent after the addition, ie :
+* if an IAP is added, it must have a parent AAP or at least a parent SAP
+for the same role
+
+If all those checks are ok, we can add the entry into the base, and update
+the AP cache
+
+## Deleting an AP entry
+This operation is way simpler, as we can't delete an entry if it has some
+children, so there is no need to check that the administrative model is
+consistent.
+
+We just have to remove the entry and update the AP cache
+
+## Modifying an AP entry
+This is way more complex. We can have five kind of modification here :
+* addition of roles
+* deletion of roles
+* replacement of roles
+* creation of a new AdministrativeRole attribute
+* removing of an existing AdministrativeRole attribute
+
+The three first modifications can imply more than one role. We have to deal
+with each of those modifications one by one.
+
+### Addition of roles
+For this modification, we will have to check for each of the roles the very
+same elements than for the Add operation above :
+* if the entry does not have an AdministrativeRole AT, we have to create it
+* we must have at least one value
+* the role must be syntaxicaly correct
+* it should not already exist into the attribute
+* we can't add it if we already have an AAP role
+* we can't add it if it's an IAP and a SAP with the same role exists
+* if it's an IAP, it must have a parent AAP or SAP with the same role
+
+If all of those checks are ok, we can update the AP cache, which must be
+cloned, otherwise we may have to rollback the operation if any of the
+following modification fails.
+
+### Removing of roles
+First, if there is no value for this modification, then that means we must
+delete the Attribute. This case will be analyzed later.
+For each of the role to remove, we have to apply those checks :
+* the role must be syntaxicaly correct
+* it must already exist into the attribute
+* we can't remove an AAP or a SAP if there is a direct IAP in one of its
+direct descendant (ie, if we have a SAP or an AAP while descending into the
+tree, we can stop checking the branch)
+
+Now, if there are no values, we have to get the existing roles and apply he
+same checks
+
+If everything is fine, we can remove the roles from the attribute.
+
+### Replacing roles
+This kind of modifications are not currently supported
+
+## Moving an AP
+As we move the entry, we may induce some inconsistencies in the AP tree. 
+
+The problem we might have is that if we move an entry having an IAP in a
+place where this role has no parent AAP or parent SAP with the same role,
+then the AdministrativeModel tree will be inconsistent. We have to check
+this.
+
+# Impact on the existing entries
+
+When we add or remove a role in a server, it may have a huge impact on the
+existing entries, as soon as those roles are associated with some
+subtreeSpecification which defines a set of contained entries. If we remove
+such a role, all the entries pertaining to the associated area have to be
+updated.
+
+It's the same thing if we add a SAP or a AAP, as all the children entries
+which were depending on a higher AP will be modified either.
+
+In any case, we don't even need to define a SubtreeSpecification, as soon
+as an AAP or SAP is created, it excludes all the children entries from any
+other higher AP areas.
+
+## Adding a Role
+Whatever the way we used to add a role (add an entry, modify an existing
+one), there are one thing we have to do depending on the kind of role we
+added. Of course, we stop modifying entries when another lower SAP or AAP
+is defined.
+
+### Adding an AAP
+All the children which were pointing to any higher IAP, SAP or AAP will be
+dereferenced. If a subtree specification is added under the newly added
+AAP, then all the associated entries will be updated.
+
+### Adding a SAP
+All the children which were pointing to any higher IAP or SAP with the same
+type of role, or an AAP, will be dereferenced (of course, only for the
+added type of role, the other references will remain). If a subtree
+specification is added under the newly added SAP, then all the associated
+entries will be updated.
+
+### Adding an IAP
+All the children which were pointing to any higher IAP with the same type
+of role will be dereferenced, and will now point to this newly added IAP.
+All the children which were pointing on a SAP with the same role, or an
+AAP, will be modified to also point on the newly added IAP.
+
+## Removing a role
+Depending on the kind of role we removed, we will have to update the
+entries accordingly.
+
+### Removing an AAP
+All the entries referencing the removed AAP will be updated, and will now
+reference the inherited AAP, SAP and IAP (if any). If there is some higher
+IAP, we will also reference it.
+
+### Removing a SAP
+All the entries referencing the removed SAP will be updated, and will now
+reference either the parent AAP or the parent SAP with the same role, if
+any. We will also reference an IAP with the same role if we have some
+higher in the hierarchy.
+
+### Removing an IAP
+All the entries referencing the removed IAP will be updated. There is
+nothing else to do.