NOT-YET-STANDARD Extensions to the WVCM (JSR-147) API
by
PeterNevermann, Software AG
Searching:
Links to the Javadoc
-> doSearch method
This extension allows clients to perform
queries. It mainly exposes the WebDAV/DASL functionality within WVCM.
Queries can be property-based and/or
content-based.
Property-based queries select resources by
their property values. The usual operators are supported: EQ (=), GT (>), GE
(>=), LT (<), LE (<=) and LIKE (~).
Content-based queries select resources by
their content. Supported operators are CONTAINS (for text resources, selecting
content containing a specified substring) and XPATH (particularly for XML
content, selecting content according to the specified XPath filter).
The scope of a query (set of resources to be
searched) is generally given by a subtree of the URI space.
In order to issue a query, a doSearch
request is applied to the root Resource of the scope-defining subtree of the
query (normally a Folder). A doSearch request returns a List of Resource
objects and takes 2 arguments:
- wanted properties (PropertyNameList, which
allows to specify the properties the resulting Resource objects are to be
loaded with), and
- search token (SearchToken, which specifies
the properly query).
Each of these arguments may be null: a null
PropertyNameList argument means, that no property values are loaded for the
resulting resources; a null SearchToken argument means that no filtering takes
place, i.e. all resources in the scope of the query are returned. [A doSearch
request with null SearchToken argument is similar to a doReadProperties
request.]
Within a doSearch request and when
querying XML content, the PropertyNameList argument may contain a special type
of AttributeName, so called XPath-based pseudo-attributes (or pseudo-attributes
for short). Such a pseudo-attribute is defined, by supplying an attribute name
and an XPath expression which, evaluated on the resource content, yields the
attribute value. So, pseudo-attributes are used to expose fragments of the XML
content as attribute values, allowing sorting for instance. NOTE, that
pseudo-attributes are not modifiable via setAttribute and doWriteProperties!
A SearchToken is defined through four
parameters:
- search condition (SearchCondition)
- sorting criteria (SortCriterion[])
- depth, to limit the scope of the query
(Depth)
- limit, to limit the number of returned
results (Integer)
The SearchCondition consists mainly of an
expression. There are three types of expression: PropertyExpression,
ContentExpression and NestedExpression.
A PropertyExpression is used to select
resources by property values, e.g. (see above for supported operators):
- CONTENT_LANGUAGE =
java.util.Locale.ENGLISH
- DISPLAYNAME ~ "%.xml" (wildcard characters according to the
WebDAV/DASL specification)
- CONTENT_LENGTH < 4000
A ContentExpression is used to select
resources by their content, e.g. (see above for supported operators):
- <content> CONTAINS
"JSR-147"
- <XML content satisfies> XPATH
"/book[@author='Donna Leon']"
A NestedExpression is used to combine other
expressions (including, of course, other nested expressions) by means of the
logical operators AND and OR.
The following sample code builds-up a nested
expression for [(DISPLAYNAME ~ "%.xml" AND
<content> CONTAINS "JSR-147") OR CONTENT_LENGTH <
4000]:
Expression e1 = new
PropertyExpression(PropertyName.DISPLAY_NAME, "%.xml",
PropOperator.LIKE, Boolean.TRUE);
Expression e2 = new
ContentExpression("JSR-147", ContOperator.CONTAINS);
Expression e3 = new
PropertyExpression(PropertyName.CONTENT_LENGTH, new Integer(4000),
PropOperator.LT, Boolean.FALSE);
Expression expression = new
NestedExpression(
new Expression[]{
new NestedExpression(
new Expression[]{
e1, e2
}, LogOperator.AND
), e3
}, LogOperator.OR
);
A SortCriterion is used to sort the result
set by the values of a specified property. It is defined mainly by a
PropertyName and an OrderDirection flag (values: ASCENDING, DESCENDING). A
SearchToken may contain multiple SortCriterion instances, in which case is
first sorted by the first criterion, then by the sencond one, and so on.
The Depth parameter is used to limit the
scope of the query in depth. Possible values are: ZERO, ONE and INFINITY.
Finally, the limit parameter is used to
limit the result set. For example, specifying a limit of 10 causes only the
first 10 results to be returned.
Access Control:
Links to the Javadoc
-> doReadAccessControlList method
-> doWriteAccessControlList method
-> getOwner method (OWNER property)
-> getPrincipalFolderList
(PRINCIPAL_FOLDER_LIST property)
-> getPrivilegeFolderList
(PRIVILEGE_FOLDER_LIST property)
-> getSupportedPrivilegeList
(SUPPORTED_PRIVILEGE_LIST property)
Overview
This extension permits a client to read and
modify access control lists that instruct a server whether to allow or deny
operations upon a resource by a given principal. It mainly exposes the
WebDAV/ACL functionality within WVCM.
The underlying principle of access control
is that who you are determines what operations you can perform on a resource.
The "who you are" is defined by a Principal object.
Special types of Principal are Group and Role.
A group is a principal that represents a set of other principals. A role can be
seen as a dynamically defined group of principals. A plain non-group and
non-role principal is also called a "user". The relationship between
users, groups and roles is defined by means of the properties GROUP_MEMBER_LIST
and GROUP_MEMBERSHIP. These two properties are inverse to each other: if a user
U1 is a member of the group G1, then U1 appears in the GROUP_MEMBER_LIST of G1,
and G1 appears in GROUP_MEMBERSHIP of U1.
In order to specify what principals, can
perform what operations on a resource, an access control list (ACL) is defined
on the resource by applying a doWriteAccessControlList request. An ACL
is a List of AccessControlElement (ACE) objects. An "ACE" either grants
or denies a particular set of privileges for a particular Principal.
ACL Evaluation is described in the
WebDAV/ACL specification, section 6.
As in the case of principals (Principal),
privileges (Privilege) represent a particular type of Resource. The two
Resource properties PRINCIPAL_FOLDER_LIST and PRIVILEGE_FOLDER_LIST tell the
locations where principals and privileges can be accessed on the server. The
property values contain the lists of folders that contain users, groups and
roles (PRINCIPAL_FOLDER_LIST) and privileges (PRIVILEGE_FOLDER_LIST).
The following generic Principal objects can
be used in ACEs:
- ALL to grant or deny privileges to all
principals
- SELF to grant or deny privileges on a
principal resource to the user it represents
- OWNER to grant or deny privileges to the
owner of a resource
- AUTHENTICATED to grant or deny privileges
to unauthenticated users
- UNAUTHENTICATED to grant or deny
privileges to unauthenticated users
Similarly, the generic Privilege object ALL
can be used in ACEs to grant or deny all privileges to a particular Principal.
Privileges can be aggregated. The
aggregation relationship between privileges is defined through the properties
PRIVILEGE_MEMBER_LIST and PRIVILEGE_MEMBERSHIP, which are inverse to each other.
For instance, the write privilege can aggregate the write-properties
and write-content privileges. As a result, a principal has automatically
the write-content privilege on a resource on which he has been granted
the write privilege.
Applying a doReadAccessControlList
request can retrieve the ACL of a Resource. It can be specified whether to
include the inherited ACEs. An "inherited ACE" is an ACE that is
dynamically shared from the ACL of another resource. When a shared ACE changes
on the primary resource, it is also changed on inheriting resources. The getInheritedFrom
method of an AccessControlElement specified the Resource from which the ACE was
inherited.
Locking:
Links to the Javadoc
-> void doLock(Timeout timeout,
boolean deep) method
-> void doLock(Timeout timeout,
boolean deep, boolean exclusive, String ownerInfo) method
-> void doUnlock() method
-> void doUnlock(LockToken token)
method
-> List[LockToken] getLockTokens()
method
Overview
This extension exposes the WebDAV locking
functionality to WVCM. For terminology, refer to the WebDAV specifications.
In order to lock a Resource, a doLock
request is issued. The request may fail, e.g. because it is already exclusively
locked by another user. The request is expected to succeed when the Resource
was not locked before, or if the resource was locked by the same user. If the
request succeeds, a new LockToken is set to the Resource. The request takes
four boolean arguments:
- timeout (number-of-seconds the lock will
last or INFINITY)
- deep (lock the whole subtree rooted by the
resource or just the resource itself)
- exclusive (exclusive or shared lock)
- ownerInfo (info about the lock owner)
A second signature of doLock without
only the first two arguments issues the request with exclusive=true and
ownerInfo="".
Just before a LockToken expires (due to its
timeout settings), the lock owner can re-issue a doLock request in order
to refresh the lock.
Lock-tokens are released by using the doUnlock
request or, automatically, by expiration. For the doUnlock request to
succeed, either the current user must match the Principal owning the lock, or
the current user must have the unlock privilege on the resource (e.g. an
administrator). Normally, the request takes no arguments. An alternate
signature of doUnlock allows to specify one of the resource's shared
lock-tokens to enable an administrator to release a single shared lock owned by
somebody else.
Lock-tokens existing for a resource at
server side are automatically retrieved when e.g. a doReadProperties, doReadContent,
doSearch or doReadMemberList request is issued. The getLockToken
method is used to access the LockToken instances from the resource proxy .
A LockToken instance contains the following
information:
- lock-ID (an URI in the opaquelocktoken:
scheme)
- exclusive (true or false)
- deep (true or false)
- owner (reference to the lock-owning
Principal)
- owner-info (additional info about the
owner)
- timeout (number of seconds, the timeout
will still last, or INFINITE)
- lock-root (reference to the Resource where
the lock is rooted)
- for-unlock-only (if true, the token is
sent to the server only on doUnlock requests, otherwise on all requests)
When lock-tokens are retrieved for a
resource (see above), the for-unlock-only flag is set TRUE if-and-only-if the
current user does not match to the Principal owning the lock. In this case, if
the resource continues locked:
- attempts to modify the resource (doWriteProperties,
doWriteContent) will fail
- attempts to unlock the resource will only
succeed if the current user has the unlock privilege on the resource.
In contrast, if the Resource proxy has a
LockToken with for-unlock-only=FALSE, attempts to modify or unlock the resource
are expected to succeed.