/*
* 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.
*/
package org.apache.wicket.security.hive.authorization;
import java.io.Serializable;
import org.apache.wicket.security.hive.authorization.permissions.ActionPermission;
/**
* Abstract class for representing access to a system resource. All permissions have a
* name (whose interpretation depends on the subclass), as well as abstract functions for
* defining the semantics of the particular Permission subclass.
*
* <p>
* Most Permission objects also include an "actions" list that tells the actions that are
* permitted for the object. For example, for a <code>java.io.FilePermission</code>
* object, the permission name is the pathname of a file (or directory), and the actions
* list (such as "read, write") specifies which actions are granted for the specified file
* (or for files in the specified directory). The actions list is optional for Permission
* objects, such as <code>java.lang.RuntimePermission</code>, that don't need such a list;
* you either have the named permission (such as "system.exit") or you don't. See
* {@link ActionPermission}.
*
* <p>
* An important method that must be implemented by each subclass is the
* <code>implies</code> method to compare Permissions. Basically, "permission p1 implies
* permission p2" means that if one is granted permission p1, one is naturally granted
* permission p2. Thus, this is not an equality test, but rather more of a subset test.
*
* <P>
* Permission objects are similar to String objects in that they are immutable once they
* have been created. Subclasses should not provide methods that can change the state of a
* permission once it has been created.
*
* All permissions must at least have a public constructor accepting a String parameter
* which will be used as name for the permission. Note that the {@link ActionPermission}
* should also have a 2 argument constructor accepting a string as the name and a second
* {@link org.apache.wicket.security.actions.WaspAction} parameter to indicate which
* actions are allowed.
*
* @author marrink
*
*/
public abstract class Permission implements Serializable
{
private static final long serialVersionUID = 4375839229178388379L;
private final String name;
/**
* Constructs a permission with a certain name.
*
* @param name
*/
public Permission(String name)
{
this.name = name;
}
/**
* Check if this permission implies the specified permission.
*
* @param permission
* @return true if this implies the permission, false otherwise.
*/
public abstract boolean implies(Permission permission);
/**
* Checks two Permission objects for equality.
* <P>
* Do not use the <code>equals</code> method for making access control decisions; use
* the <code>implies</code> method.
*
* @param obj
* the object we are testing for equality with this object.
*
* @return true if both Permission objects are equivalent.
*/
@Override
public abstract boolean equals(Object obj);
/**
* Returns the hash code value for this Permission object.
* <P>
* The required <code>hashCode</code> behavior for Permission Objects is the
* following:
* <p>
* <ul>
* <li>Whenever it is invoked on the same Permission object more than once during an
* execution of a Java application, the <code>hashCode</code> method must consistently
* return the same integer. This integer need not remain consistent from one execution
* of an application to another execution of the same application.
* <p>
* <li>If two Permission objects are equal according to the <code>equals</code>
* method, then calling the <code>hashCode</code> method on each of the two Permission
* objects must produce the same integer result.
* </ul>
*
* @return a hash code value for this object.
*/
@Override
public abstract int hashCode();
/**
* Returns the actions as a String. This is abstract so subclasses can defer creating
* a String representation until one is needed. Subclasses should always return
* actions in what they consider to be their canonical form. For example, two
* FilePermission objects created via the following:
*
* <pre>
* perm1 = new FilePermission(p1, "read,write");
* perm2 = new FilePermission(p2, "write,read");
* </pre>
*
* both return "read,write" when the <code>getActions</code> method is invoked.
*
* @return the actions of this Permission.
*
*/
public abstract String getActions();
/**
* Returns the name of this Permission. For example, in the case of a
*
* <code>org.apache.wicket.security.hive.authorization.permissions.ComponentPermission</code>
* , the name will be a component path.
*
* @return the name of this Permission.
*
*/
public final String getName()
{
return name;
}
}