Jena Permissions - Migration notes: Version 2.x to Version 3.x

When Jena moved from version 2 to version 3 there was a major renaming of packages. One of the packages renamed was the Jena Permissions package. It was formerly named Jena Security. There are several changes that need to occur to migrate from jena-security version 2.x to jena-permissions version 3.x.

Changes

Package Rename

There are two major changes to package names.

  • As with the rest of the Jena code all references to com.hp.hpl.jena have been changed to org.apache.jena. For integrator code this means that a simple rename of the includes is generally all that is required for this. See the main Migration Notes page for other hints and tips regarding this change.

  • Jena Security has been renamed Jena Permissions and the Maven artifact id has been changed to jena-permissions to reflect this change.

  • The permissions assembler namespace has been changed to http://apache.org/jena/permissions/Assembler#

Exceptions

Formerly Jena Permissions uses a single exception to identify the access restriction violations. With the tighter integration of permission concepts into the Jena core there are now 7 exceptions. This change will probably not required modification to the SecurityEvaluator implementation but may require modification to classes that utilize the permissions based object.

All exceptions are runtime exceptions and so do not have to be explicitly caught. Javadocs indicate which methods throw which exceptions.

  • Removal of org.apache.jena.permissions.AccessDeniedException. This is replace by 5 individual exceptions.

  • Addition of org.apache.jena.shared.OperationDeniedException. This exception is a child of the JenaException and is the root of all operation denied states whether through process errors or through permissions violations.

  • Addition of org.apache.jena.shared.PermissionDeniedException. This exception is a child of the OperationDeniedException and is the root of all operations denied through permission violations. These can be because the object was statically prohibited from performing an operation (e.g. a read-only graph) or due to the Jena Permissions layer.

  • Addition of org.apache.jena.shared.AddDeniedException. This exception is a child of PermissionDeniedException and used to indicate that an attempt was made to add to an unmodifiable object. It may be thrown by read-only graphs or by the permission layer when a create restriction is violated.

  • Addition of org.apache.jena.shared.DeleteDeniedException. This exception is a child of PermissionDeniedException and used to indicate that an attempt was made to delete from an unmodifiable object. It may be thrown by read-only graphs or by the permission layer when a delete restriction is violated.

  • Addition of org.apache.jena.shared.ReadDeniedException. This exception is a child of PermissionDeniedException and used to indicate that a read restriction was violated.

  • Addition of org.apache.jena.shared.UpdateDeniedException. This exception is a child of PermissionDeniedException and used to indicate that a update restriction was violated.

  • Addition of org.apache.jena.shared.AuthenticationRequiredException. This exception is a child of OperationDeniedException and used to indicate that user authentication is required but has not occurred. This exception should be thrown when the SecurityEvaluator attempts to evaluate an operation and there is both a permissions restriction and the object returned by getPrincipal() indicates that the user is unauthenticated.

Removal of Classes

The original “security” code was intended to be graph agnostic and so injected a “shim” layer to convert from graph specific classes to security specific classes. With the renaming of the package to “permissions” and the tighter integration to the Jena core the “shim” structure has been removed. This should make the permissions layer faster and cleaner to implement.

SecNode

The SecNode class has been removed. This was effectively a proxy for the Jena Node object and has been replaced with that object. The SecNode maintained its type (e.g. URI, Literal or Variable) using an internal Enumeration. The method getType() was used to identify the internal type. With the Jena node replacement statements of the form

 if (secNode.getType().equals( SecNode.Type.Literal ))
 {
     // do something
 }

are replaced with

 if (node.isLiteral())
 {
     // do something
 }

SecNode.ANY has been replaced with Node.ANY as it served the same purpose.

SecNode.FUTURE has been replaced with SecurityEvaluator.FUTURE and is now implemented as a blank node with the label urn:jena-permissions:FUTURE.

SecNode.VARIABLE has been replaced with SecurityEvaluator.VARIABLE and is now implemented as a blank node with the label urn:jena-permissions:VARIABLE.

SecTriple

The SecTriple class has been removed. This was effectively a proxy for the Jena Triple object and has been replaced with that object.

Movement of Classes

SecuredItem

The SecuredItem interface was moved from org.apache.jena.permissions.impl to org.apache.jena.permissions.

Additional Methods

SecurityEvaluator

The method isAuthenticatedUser( Object principal ) has been added. The SecurityEvaluator should respond true if the principal is recognized as an authenticated user. The principal object is guaranteed to have been returned from an earlier getPrincipal() call.