content/apacheds/advanced-ug/3.2-operations-on-an-administrativepoint.mdtext

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-authentication-and-authorization.html
NavNextText: 4 - Authentication and Authorization
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.

# 3.2 Operations on an Administrative Point
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 roles 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.