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    }