AcegiSecruity acl包javadoc笔记

不知道怎么配Acegi的Acl只好看JavaDoc了，做了些笔记，只有org.acegisecurity.acl.basic.jdbc 包没写完，因为倾向与不使用Acegi的Acl了....：

org.acegisecurity.acl包：

Package org.acegisecurity.acl Description
Enables retrieval of access control lists (ACLs) for domain object instances.

The goal of this package is to locate the AclEntrys that apply to a given domain object instance.

An AclManager has ultimate resposibility for obtaining the AclEntrys instances, with a provider-based implementation available via the AclProviderManager class (and its AclProvider interface.

包描述：
提供检索域对象实例的访问控制列表的能力。
该包的目标是定位应用在一个给定域对象实例上的AclEntrys.
AclManager负责取得AclEntrys实例。？？？？（后面半句不好翻）

三个接口一个类：

Interface:

AclEntry： Marker interface representing an access control list entry associated with a specific domain object instance.
标记接口，表示一个访问控制列表的条目，该条目与一个特定的域对象实例相联系。

AclManager： Obtains the AclEntry instances that apply to a particular domain object instance.
取得应用在一个特定域对象实例上的AclEntry实例(注意是复数)。

AclProvider： Indicates a class can process a given domain object instance and authoritatively return the ACLs that apply.
说明一个类是否能处理一个给定的域对象实例并且能够可靠的返回应用在这个域对象实例上的ACLs;

Class：
AclProviderManager： Iterates through a list of AclProviders to locate the ACLs that apply to a given domain object instance.
遍历AclProvider列表来定位应用在给定域对象上的ACLs.

说明：
AclEntry是一个口接口，只起到标记的作用。真正具有意义的是其子接口BasicAclEntry。
AclManger和AclProvider接口，定义的方法有两个都一样，都是：
AclEntry[] getAcls(Object domainInstance) ：Obtains the ACLs that apply to the specified domain instance.
AclEntry[] getAcls(Object domainInstance, Authentication authentication) ：Obtains the ACLs that apply to the specified domain instance, but only including those ACLs which have been granted to the presented Authentication object
做什么用的就不翻译了，很简单的。

但AclProvider还多一个方法：
boolean supports(Object domainInstance) ：Indicates whether this AclProvider can authoritatively return ACL information for the specified domain object instance.
就是判断当前AclProvider是否能够取得给定域对象实例的ACL信息。如果返回为false,则getAcls方法不能执行。

我想，大概是AclManger需要用到AclProvider，当域对象实例传入AclManger的getAcls方法后，AclManger的方法再逐个调用它所引用的AclProvider来得到AclEntrys.

AclProviderManager类就继承了AclManger接口，也就是AclManger的一个实现。它还实现了org.springframework.beans.factory.InitializingBean接口，该接口有一方法：
void afterPropertiesSet() ：Invoked by a BeanFactory after it has set all bean properties supplied (and satisfied BeanFactoryAware and ApplicationContextAware).
This method allows the bean instance to perform initialization only possible when all bean properties have been set and to throw an exception in the event of misconfiguration.
大概是与Spring中Bean的初始化有关，这个就先不管了。不过觉得有点侵入性...

另外两个方法很好理解：
List getProviders()
           
void setProviders(List newList)：Sets the AclProvider objects to be used for ACL determinations.

****package*************************************************

下面看org.acegisecurity.acl.basic包：

包描述：Access control list implementation based on integer bit masks.
整数位掩码的ACL实现。
看来这个包是提供一个基本的ACL实现，恩，要好好看下。

Interface:

AclObjectIdentity: Interface representing the identity of an individual domain object instance.
表示一个单独的域对象实例的标识。

AclObjectIdentityAware： Indicates a domain object instance is able to provide AclObjectIdentity information.
说明一个域对象实例是否能够提供AclObjectIdentity的信息。

BasicAclDao： Represents a data access object that can return the BasicAclEntrys applying to a given ACL object identity.
表示一个数据访问对象，该对象能够返回应用在给定ACL对象标识上的BasicAclEntrys.

BasicAclEntry： Represents an entry in an access control list.
表示一个访问控制列表的条目。

BasicAclEntryCache： Provides a cache of BasicAclEntry objects.
提供BasicAclEntry对象的缓存。

BasicAclExtendedDao： Represents a more extensive data access object for BasicAclEntrys.
表示一个BasicAclEntrys的扩展的访问对象。

EffectiveAclsResolver： Determines the ACLs that are effective for a given Authentication object
确定对一个给定的鉴权对ACLs是否有效。

Class:

AbstractBasicAclEntry: Abstract implementation of BasicAclEntry.
BasicAclEntry的抽象实现。

BasicAclProvider： Retrieves access control lists (ACL) entries for domain object instances from a data access object (DAO).
从DAO中检索域对象实例的访问控制列表。

GrantedAuthorityEffectiveAclsResolver： Simple implementation of EffectiveAclsResolver.
EffctiveAclsResolver接口的简单实现。

NamedEntityObjectIdentity： Simple implementation of AclObjectIdentity.
AclObjectIdentity接口的简单实现。

SimpleAclEntry: Stores some privileges typical of a domain object.
存储一些权限，典型的如域对象的权限。

说明：

AclObjectIdentity，就两个方法，一个是equals一个是hashCode这两个方法就是用来判断两个对象是否相同，可能主要用在cache中吧。
该接口说明中还提到了对象相等和引用相等的问题。
总之，该接口就是用来区分不同的对象实例。下面看看该接口的一个实现：

=====Interface or Class====================

NamedEntityObjectIdentity，在acegi的参考文档中，这个实现可以满足大多数的应用。
这个类有三个构造函数，除了默认构造函数外，一个是通过对象来构造，一个是通过类名和对象id来构造。除了要实现的两个方法外，还有：
public String getClassname()，这个见名就知道意思了。
public String getId()
public String toString()  Overrides:toString in class Object

看到这还是不大明白这个接口及其实现要起到个什么作用。

=====Interface or Class====================

AclObjectIdentityAware接口：
Domain objects must implement this interface if they wish to provide an AclObjectIdentity rather than it being determined by relying classes. Specifically, the BasicAclProvider detects and uses this interface.
域对象可以实现这个接口，如果想让其自己提供AclObjectIdentity,而不是通过辅助类的话。自己实现这个接口就会有侵入性了。查看了contact的类，并没有实现这个接口。所以，基本上，用不到这个：）
AclObjectIdentity getAclObjectIdentity()Retrieves the AclObjectIdentity for this instance.
就是返回这个实例的AclObjectIdentity.

=====Interface or Class====================

BasicAclDao接口：只有一个方法，就是通过AclObjectIdentity取得AclEntrys,如下：
BasicAclEntry[] getAcls(AclObjectIdentity aclObjectIdentity)
这个方法有如下说明需要注意：
Does not perform caching, include ACLs from any inheritance hierarchy or filter returned objects based on effective permissions. Implementations are solely responsible for returning ACLs found in the ACL repository for the specified object identity.
大概的意思是说缓存不要建在Dao这个层次上。
这个接口的子接口和实现类：
All Known Subinterfaces:
BasicAclExtendedDao
All Known Implementing Classes:
JdbcDaoImpl, JdbcExtendedDaoImpl
两个实现类应该在jdbc包里，那就到那个包再说吧。

=====Interface or Class====================

BasicAclExtendedDao接口：
All Superinterfaces:
BasicAclDao
All Known Implementing Classes:
JdbcExtendedDaoImpl
显示是继承上一个接口的：

BasicAclExtendedDao implementations are responsible for interpreting a a given AclObjectIdentity.
好象是是说该实现负责解释给定的AclObjectIdentity.

除了父接口中的方法，还有如下方法：
void changeMask(AclObjectIdentity aclObjectIdentity,
                Object recipient,
                Integer newMask)
                throws DataAccessExceptionChanges
the permission mask assigned to the BasicAclEntry associated with the specified AclObjectIdentity and recipient Object.
也就是改变一个实例的许可，因为一个实例可以有多个许可，所以还要加上对应的recipient.

void create(BasicAclEntry basicAclEntry)
            throws DataAccessExceptionThrows:
DataAccessException
显然是创建一个新条目：

void delete(AclObjectIdentity aclObjectIdentity)
            throws DataAccessException
删除实例对应的所有条目

void delete(AclObjectIdentity aclObjectIdentity,
            Object recipient)
            throws DataAccessException
删除根据指定的recipient删除与实例相关的条目

=====Interface or Class====================

BasicAclEntry接口：
All Superinterfaces:
AclEntry, Serializable
All Known Implementing Classes:
AbstractBasicAclEntry, SimpleAclEntry

这就是具有真正意义的acl entry接口了，方法有9个，还真不少。一个方法一个方法说吧：

AclObjectIdentity getAclObjectIdentity()：
Indicates the domain object instance that is subject of this BasicAclEntry. This information may be of interest to relying classes (voters and business methods) that wish to know the actual origination of the ACL entry (so as to distinguish individual ACL entries from others contributed by the inheritance hierarchy).
应该返回的是从属于这个AclEntry对象实例的AclObjectIdentity。

AclObjectIdentity getAclObjectParentIdentity() ：Indicates any ACL parent of the domain object instance.
Indicates any ACL parent of the domain object instance. This is used by BasicAclProvider to walk the inheritance hierarchy. An domain object instance need not have a parent
返回父实例的AclObjectIdentity，一便于BasicAclProvider沿着继承结构移动。

int getMask()：Access control lists in this package are based on bit masking. The integer value of the bit mask can be obtained from this method.
就是得到访问列表的掩码。

Object getRecipient():A domain object instance will usually have multiple BasicAclEntrys. Each separate BasicAclEntry applies to a particular "recipient". Typical examples of recipients include (but do not necessarily have to include) usernames, role names, complex granted authorities etc.
这个方法返回AclEntry的接受者，可以是角色，可以是用户，或者是其他的授权。
It is essential that only one BasicAclEntry exists for a given recipient. Otherwise conflicts as to the mask that should apply to a given recipient will occur.
本质上，一个ACL条目只存在一个给定的接受者，否则的话会产生掩码冲突。

boolean isPermitted(int permissionToCheck)：Determine if the mask of this entry includes this permission or not
确定该条目的掩码是否具有许可。应该就是检查该条目是否包含某一授权吧。

其他四个setter方法，就不说了。

=====Interface or Class====================

接着看看AclEntry的一个实现类：
AbstractBasicAclEntry：
All Implemented Interfaces:
Serializable, AclEntry, BasicAclEntry
Direct Known Subclasses:
SimpleAclEntry

Provides core bit mask handling methods. 它提供核心的位掩码处理函数。
有两个构造函数，看非默认的（默认的还是protected的）：
AbstractBasicAclEntry(Object recipient, AclObjectIdentity aclObjectIdentity, AclObjectIdentity aclObjectParentIdentity, int mask)
该函数就是创建一个完整的访问列表条目。

其他函数一大堆，超过20个吧，但有些是继承了接口的，就不说了：
讲讲不是接口的吧：
addPermission
public int addPermission(int permissionToAdd)
增加一个许可

addPermissions
public int addPermissions(int[] permissionsToAdd)
增加多个许可

deletePermission
public int deletePermission(int permissionToDelete)
删除一个许可

deletePermissions
public int deletePermissions(int[] permissionsToDelete)
删除多个许可

isPermitted
protected boolean isPermitted(int maskToCheck,
                              int permissionToCheck)
这个，功能与接口的差不多，只是不是检查本条目的mask,而是任意输入的。

printPermissionsBlock
public String printPermissionsBlock()
Outputs the permissions in human-friendly format for the current AbstractBasicAclEntry's mask.
Returns:
the human-friendly formatted block for this instance
也就是得到友好的条目许可说明：）

printPermissionsBlock
public abstract String printPermissionsBlock(int i)Outputs the permissions in a human-friendly format. For example, this method may return "CR-D" to indicate the passed integer permits create, permits read, does not permit update, and permits delete.

Parameters:
i - the integer containing the mask which should be printed
指定mask的友好说明。

下面这个方法要注意：
getValidPermissions
public int[] getValidPermissions()
Subclasses must indicate the permissions they support. Each base permission should be an integer with a base 2. ie: the first permission is 2^^0 (1), the second permission is 2^^1 (2), the third permission is 2^^2 (4) etc. Each base permission should be exposed by the subclass as a public static final int. It is further recommended that valid combinations of permissions are also exposed as public static final ints.
This method returns all permission integers that are allowed to be used together. This must include any combinations of valid permissions. So if the permissions indicated by 2^^2 (4) and 2^^1 (2) can be used together, one of the integers returned by this method must be 6 (4 + 2). Otherwise attempts to set the permission will be rejected, as the final resulting mask will be rejected.

Whilst it may seem unduly time onerous to return every valid permission combination, doing so delivers maximum flexibility in ensuring ACLs only reflect logical combinations. For example, it would be inappropriate to grant a "read" and "write" permission along with an "unrestricted" permission, as the latter implies the former permissions.

方法说明大概是说每个permission对应的整数，必须是按2的n次方定义的，如1，2，4，8，16...这样定义，以及掩码的使用方法。这个我懂，就不翻了，大概就是用按位与来得到mask中是否有这个permision.
这个方法就是得到所有的可用的permission整数。

togglePermission
public int togglePermission(int permissionToToggle)
没有说明，字面好象是绑定许可的意思，不清楚啊？？？？？？？？？？？

toString
public String toString()
这个就不用说了吧：）

=====Interface or Class====================

接着上一个类往下继承：
SimpleAclEntry类：
All Implemented Interfaces:
Serializable, AclEntry, BasicAclEntry

该类定义了一些静态属性，应该就是掩码的值吧，这里就不列了。构造函数两个，与abstrct类相同。
有两个方法重载了父类的方法，是：

int[] getValidPermissions()
          Subclasses must indicate the permissions they support.
String printPermissionsBlock(int i)
          Outputs the permissions in a human-friendly format.

功能上没有什么不同。

=====Interface or Class====================
BasicAclEntryCache接口：

All Known Implementing Classes:
EhCacheBasedAclEntryCache, NullAclEntryCache

Implementations should provide appropriate methods to set their cache parameters (eg time-to-live) and/or force removal of entities before their normal expiration. These are not part of the BasicAclEntryCache interface contract because they vary depending on the type of caching system used (eg in-memory vs disk vs cluster vs hybrid).

实现必须提供合适的方法来设置缓存的参数（如生存时间）和/或者在缓存正常期限到期前强制将其移除。这不是该接口规定的，因为这些需要根据不采用的不同的缓存系统来决定（缓存在内存中，磁盘中，磁盘簇中或者是混合方案）。

需要实现的方法：

BasicAclEntry[] getEntriesFromCache(AclObjectIdentity aclObjectIdentity)
Obtains an array of BasicAclEntrys from the cache.
根据实例从缓存中找出Acl条目。

void putEntriesInCache(BasicAclEntry[] basicAclEntry)
Places an array of BasicAclEntrys in the cache.
把条目放入缓存

void removeEntriesFromCache(AclObjectIdentity aclObjectIdentity)
Removes all ACL entries related to an AclObjectIdentity from the cache.
移除某一实例在缓存中的条目。

 

=====Interface or Class====================
Interface EffectiveAclsResolver
All Known Implementing Classes:
GrantedAuthorityEffectiveAclsResolver

这个接口就是确定Authentication对某一ACL条目是否有效。

Implementations will vary depending on their ability to interpret the "recipient" object types contained in BasicAclEntry instances, and how those recipient object types correspond to Authentication-presented principals and granted authorities.

BasicAclEntry中"recipient"的解释和如何将recipient对象与Authentication表达形式的principals和授权相对应的不同，接口的实现也不同。
Implementations should not filter the resulting ACL list from lower-order permissions。
实现不能从低级别的授权起过滤得到的ACL列表？？？？？？？？？？？？不他懂什么意思啊

需要实现的方法就一个，如下：
AclEntry[] resolveEffectiveAcls(AclEntry[] allAcls,
                                Authentication filteredBy)
Determines the ACLs that apply to the presented Authentication object.

=====Interface or Class====================

GrantedAuthorityEffectiveAclsResolver类：
All Implemented Interfaces:
EffectiveAclsResolver

继承了上面的接口，有一大段说明，讲实现的问题。方法同上，不说了。

 

 

****package*************************************************

 

org.acegisecurity.acl.basic.cache 包：

三个class:
BasicAclEntryHolder: Used by EhCacheBasedAclEntryCache to store the array of BasicAclEntrys in the cache.
EhCacheBasedAclEntryCache用它存储BasicAclEntry数组到cache中。

EhCacheBasedAclEntryCache： Caches BasicAclEntrys using a Spring IoC defined EHCACHE.
用Spring IoC定义的EHCACHE来缓存BasicAclEntrys。

NullAclEntryCache：Does not perform any caching.
不进行任何缓存。

=====Interface or Class====================

BasicAclEntryHolder类：

This is necessary because caches store a single object per key, not an array.
这个类之所以需要是因为缓存时每个键对应一个单独的对象而不是一个数组。
This class uses value object semantics. ie: construction-based initialisation without any setters for the properties.
这个列使用值对象语意，即构造时初始化，属性不具有任何setter方法。

构造函数：
Constructor Summary
BasicAclEntryHolder(BasicAclEntry[] aclEntries)
          Constructs the BasicAclEntryHolder.
方法：
BasicAclEntry[] getBasicAclEntries() 

看来这个类就是把一个数组包成一个对象：），方便缓存。

 

=====Interface or Class====================
EhCacheBasedAclEntryCache类：

All Implemented Interfaces:
BasicAclEntryCache, InitializingBean

前面介绍了，就是用来cache BasicAclEntry的，不过用了Spring的ENCACHE功能。怪不得实现了InitlializingBean.

下面是方法：
void afterPropertiesSet()  不说了
public net.sf.ehcache.Cache getCache() 得到缓存
public void setCache(net.sf.ehcache.Cache cache) 设置缓存
其他的三个方法是实现接口的方法，在前面介绍过了

BasicAclEntry[] getEntriesFromCache(AclObjectIdentity aclObjectIdentity)
          Obtains an array of BasicAclEntrys from the cache.

void putEntriesInCache(BasicAclEntry[] basicAclEntry)
          Places an array of BasicAclEntrys in the cache.

void removeEntriesFromCache(AclObjectIdentity aclObjectIdentity)
          Removes all ACL entries related to an AclObjectIdentity from the cache.

=====Interface or Class====================
NullAclEntryCache类：
All Implemented Interfaces:
BasicAclEntryCache

一般不用，不实现任何缓存，实现了接口的三个方法。

 

****package*************************************************

org.acegisecurity.acl.basic.jdbc 包：

两个类：
JdbcDaoImpl：Retrieves ACL details from a JDBC location.
从JDBC数据源检索ACL的详细信息。

JdbcExtendedDaoImpl： Extension of the base JdbcDaoImpl, which implements BasicAclExtendedDao.
扩展JdbcDaoImpl, 实现了BasicAclExtendedDao.

 

=====Interface or Class====================

JdbcDaoImpl

All Implemented Interfaces:
BasicAclDao, InitializingBean
Direct Known Subclasses:
JdbcExtendedDaoImpl

A default database structure is assumed. This may be overridden by setting the default query strings to use. If this does not provide enough flexibility, another strategy would be to subclass this class and override the MappingSqlQuery instance used, via the initMappingSqlQueries() extension point.

有一默认的数据表结构。它能够被重载，通过设置默认的查询字符串。如果这还不能提供足够的灵活性，另外一个策略就需要创建该类的子类并且重载MappingSqlQuery实例，通过initMappingSqlQueries()扩展。

该类包括三个内建类：