    001    package org.apache.turbine.om.security;
    002
    003    /*
    004     * Licensed to the Apache Software Foundation (ASF) under one
    005     * or more contributor license agreements.  See the NOTICE file
    006     * distributed with this work for additional information
    007     * regarding copyright ownership.  The ASF licenses this file
    008     * to you under the Apache License, Version 2.0 (the
    009     * "License"); you may not use this file except in compliance
    010     * with the License.  You may obtain a copy of the License at
    011     *
    012     *   http://www.apache.org/licenses/LICENSE-2.0
    013     *
    014     * Unless required by applicable law or agreed to in writing,
    015     * software distributed under the License is distributed on an
    016     * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
    017     * KIND, either express or implied.  See the License for the
    018     * specific language governing permissions and limitations
    019     * under the License.
    020     */
    021
    022    import java.io.Serializable;
    023
    024    import org.apache.turbine.util.security.PermissionSet;
    025    import org.apache.turbine.util.security.TurbineSecurityException;
    026
    027    /**
    028     * This class represents a role played by the User associated with the
    029     * current Session.
    030     *
    031     * @author <a href="mailto:frank.kim@clearink.com">Frank Y. Kim</a>
    032     * @author <a href="mailto:john.mcnally@clearink.com">John D. McNally</a>
    033     * @author <a href="mailto:bmclaugh@algx.net">Brett McLaughlin</a>
    034     * @author <a href="mailto:hps@intermeta.de">Henning P. Schmiedehausen</a>
    035     * @version $Id: Role.java 957284 2010-06-23 17:53:31Z tv $
    036     */
    037    public interface Role extends SecurityEntity, Serializable
    038    {
    039        /**
    040         * Returns the set of Permissions associated with this Role.
    041         *
    042         * @return A PermissionSet.
    043         * @exception Exception A generic exception.
    044         */
    045        PermissionSet getPermissions()
    046            throws Exception;
    047
    048        /**
    049         * Sets the Permissions associated with this Role.
    050         *
    051         * @param permissionSet A PermissionSet.
    052         */
    053        void setPermissions(PermissionSet permissionSet);
    054
    055        // These following methods are wrappers around TurbineSecurity
    056
    057        /**
    058         * Creates a new Role in the system.
    059         *
    060         * @param name The name of the new Role.
    061         * @return An object representing the new Role.
    062         * @throws TurbineSecurityException if the Role could not be created.
    063         */
    064        Role create(String name)
    065            throws TurbineSecurityException;
    066
    067        /**
    068         * Makes changes made to the Role attributes permanent.
    069         *
    070         * @throws TurbineSecurityException if there is a problem while
    071         *  saving data.
    072         */
    073        void save()
    074            throws TurbineSecurityException;
    075
    076        /**
    077         * Removes a role from the system.
    078         *
    079         * @throws TurbineSecurityException if the Role could not be removed.
    080         */
    081        void remove()
    082            throws TurbineSecurityException;
    083
    084        /**
    085         * Renames the role.
    086         *
    087         * @param name The new Role name.
    088         * @throws TurbineSecurityException if the Role could not be renamed.
    089         */
    090        void rename(String name)
    091            throws TurbineSecurityException;
    092
    093        /**
    094         * Grants a Permission to this Role.
    095         *
    096         * @param permission A Permission.
    097         * @throws TurbineSecurityException if there is a problem while assigning
    098         * the Permission.
    099         */
    100        void grant(Permission permission)
    101            throws TurbineSecurityException;
    102
    103        /**
    104         * Grants Permissions from a PermissionSet to this Role.
    105         *
    106         * @param permissionSet A PermissionSet.
    107         * @throws TurbineSecurityException if there is a problem while assigning
    108         * the Permissions.
    109         */
    110        void grant(PermissionSet permissionSet)
    111            throws TurbineSecurityException;
    112
    113        /**
    114         * Revokes a Permission from this Role.
    115         *
    116         * @param permission A Permission.
    117         * @throws TurbineSecurityException if there is a problem while unassigning
    118         * the Permission.
    119         */
    120        void revoke(Permission permission)
    121            throws TurbineSecurityException;
    122
    123        /**
    124         * Revokes Permissions from a PermissionSet from this Role.
    125         *
    126         * @param permissionSet A PermissionSet.
    127         * @throws TurbineSecurityException if there is a problem while unassigning
    128         * the Permissions.
    129         */
    130        void revoke(PermissionSet permissionSet)
    131            throws TurbineSecurityException;
    132    }