org.apache.jackrabbit.api.security.user.Authorizable Maven / Gradle / Ivy

Go to download
/*
 * 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.jackrabbit.api.security.user;

import java.security.Principal;
import java.util.Iterator;

import javax.jcr.RepositoryException;
import javax.jcr.UnsupportedRepositoryOperationException;
import javax.jcr.Value;

/**
 * The Authorizable is the common base interface for {@link User} and
 * {@link Group}. It provides access to the Principals associated
 * with an Authorizable (see below) and allow to access and
 * modify additional properties such as e.g. full name, e-mail or address.
 * 
 * 

 * Please note the difference between Authorizable and
 * {@link java.security.Principal Principal}:

 * An Authorizable is repository object that is neither associated
 * with nor depending from a particular Session and thus independent
 * of the login mechanisms creating Sessions.

 * 

 * On the other hand Principals are representations of user
 * identities. In other words: each Principal within the set
 * associated with the Session's Subject upon login represents an identity for
 * that user. An the set of Principals may differ between different
 * login mechanisms.

 * 

 * Consequently an one-to-many relationship exists between Authorizable
 * and Principal (see also {@link #getPrincipal()}.
 * 

 * 

 * The interfaces derived from Authorizable are defined as follows:
 * 

 * {@link User}: defined to be an Authorizable that can be authenticated
 * (by using Credentials) and impersonated.
 * {@link Group}: defined to be a collection of other
 * Authorizables.
 * 
 *
 * @see User
 * @see Group
 */
public interface Authorizable {

    /**
     * Return the implementation specific identifier for this
     * Authorizable. It could e.g. be a UserID or simply the
     * principal name.
     *
     * @return Name of this Authorizable.
     * @throws RepositoryException if an error occurs.
     */
    String getID() throws RepositoryException;

    /**
     * @return if the current Authorizable is a {@link Group}
     */
    boolean isGroup();

    /**
     * @return a representation as Principal.
     * @throws RepositoryException If an error occurs.
     */
    Principal getPrincipal() throws RepositoryException;

    /**
     * @return all {@link Group}s, this Authorizable is declared member of.
     * @throws RepositoryException If an error occurs.
     */
    Iterator declaredMemberOf() throws RepositoryException;

    /**
     * @return all {@link Group}s, this Authorizable is member of included
     *         indirect group membership.
     * @throws RepositoryException If an error occurs.
     */
    Iterator memberOf() throws RepositoryException;

    /**
     * Removes this Authorizable, if the session has sufficient
     * permissions. Note, that removing an Authorizable even
     * if it listed as member of a Group or if still has members (this is
     * a Group itself).
     *
     * @throws RepositoryException If an error occurred and the
     * Authorizable could not be removed.
     */
    void remove() throws RepositoryException;

    /**
     * Returns the names of properties present with this
     * Authorizable not taking possible relative paths into consideration.
     * Same as {@link #getPropertyNames(String)} where the specified string
     * is ".".
     *
     * @return names of properties.
     * @throws RepositoryException If an error occurs.
     * @see #getProperty(String) where the specified relative path is simply an
     * name.
     * @see #hasProperty(String)
     */
    Iterator getPropertyNames() throws RepositoryException;

    /**
     * Returns the names of properties present with this
     * Authorizable at the specified relative path.
     *
     * @param relPath A relative path.
     * @return names of properties.
     * @throws RepositoryException If an error occurs.
     * @see #getProperty(String)
     * @see #hasProperty(String)
     */
    Iterator getPropertyNames(String relPath) throws RepositoryException;

    /**
     * Tests if a the property with specified name exists.
     *
     * @param relPath The relative path to the property to be tested.
     * @return true if a property with the given name exists.
     * @throws RepositoryException If an error occurs.
     * @see #getProperty(String)
     */
    boolean hasProperty(String relPath) throws RepositoryException;

    /**
     * Set an arbitrary property to this Authorizable.
     *
     * @param relPath The relative path of the property to be added or modified.
     * @param value The desired value.
     * @throws RepositoryException If the specified property could not be set.
     */
    void setProperty(String relPath, Value value) throws RepositoryException;

    /**
     * Set an arbitrary property to this Authorizable.
     *
     * @param relPath The relative path of the property to be added or modified.
     * @param value The desired property values.
     * @throws RepositoryException If the specified property could not be set.
     */
    void setProperty(String relPath, Value[] value) throws RepositoryException;

    /**
     * Returns the values for the properties with the specified name or
     * null.
     *
     * @param relPath Relative path of the property to be retrieved.
     * @return value of the property with the given name or null
     *         if no such property exists.
     * @throws RepositoryException If an error occurs.
     */
    Value[] getProperty(String relPath) throws RepositoryException;

    /**
     * Removes the property with the given name.
     *
     * @param relPath Relative path (or name) of the property to be removed.
     * @return true If the property at the specified relPath was successfully
     *         removed; false if no such property was present.
     * @throws RepositoryException If an error occurs.
     */
    boolean removeProperty(String relPath) throws RepositoryException;

    /**
     * Returns a JCR path if this authorizable instance is associated with an
     * item that can be accessed by the editing Session.
     * Throws UnsupportedRepositoryOperationException if this
     * method is not supported or if there is no item associated with this
     * authorizable that is accessible by the editing Session.
     * Throws RepositoryException if another error occurs while
     * retrieving the path.
     *
     * @return the path of the {@link javax.jcr.Item} that corresponds to this
     * Authorizable.
     * @throws UnsupportedRepositoryOperationException If this method is not
     * supported or if there exists no accessible item associated with this
     * Authorizable instance.
     * @throws RepositoryException If an error occurs while retrieving the
     * Item path.
     */
    String getPath() throws UnsupportedRepositoryOperationException, RepositoryException;
}