001/* 
002    Licensed to the Apache Software Foundation (ASF) under one
003    or more contributor license agreements.  See the NOTICE file
004    distributed with this work for additional information
005    regarding copyright ownership.  The ASF licenses this file
006    to you under the Apache License, Version 2.0 (the
007    "License"); you may not use this file except in compliance
008    with the License.  You may obtain a copy of the License at
009
010       http://www.apache.org/licenses/LICENSE-2.0
011
012    Unless required by applicable law or agreed to in writing,
013    software distributed under the License is distributed on an
014    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015    KIND, either express or implied.  See the License for the
016    specific language governing permissions and limitations
017    under the License.  
018 */
019package org.apache.wiki.auth.authorize;
020
021import java.io.Serializable;
022import java.security.Principal;
023
024/**
025 * A lightweight, immutable Principal that represents a built-in wiki role such
026 * as Anonymous, Asserted and Authenticated. It can also represent dynamic roles
027 * used by an external {@link org.apache.wiki.auth.Authorizer}, such as a web
028 * container.
029 * @since 2.3
030 */
031public final class Role implements Principal, Serializable
032{
033    private static final long serialVersionUID = 1L;
034
035    /** All users, regardless of authentication status */
036    public static final Role ALL           = new Role( "All" );
037
038    /** If the user hasn't supplied a name */
039    public static final Role ANONYMOUS     = new Role( "Anonymous" );
040
041    /** If the user has supplied a cookie with a username */
042    public static final Role ASSERTED      = new Role( "Asserted" );
043
044    /** If the user has authenticated with the Container or UserDatabase */
045    public static final Role AUTHENTICATED = new Role( "Authenticated" );
046
047    private final String   m_name;
048
049    /**
050     *  Create an empty Role.
051     */
052    Role()
053    {
054        this(null);
055    }
056    
057    /**
058     * Constructs a new Role with a given name.
059     * @param name the name of the Role
060     */
061    public Role(final String name )
062    {
063        m_name = name;
064    }
065
066    /**
067     * Returns <code>true</code> if a supplied Role is a built-in Role:
068     * {@link #ALL}, {@link #ANONYMOUS}, {@link #ASSERTED},
069     * or {@link #AUTHENTICATED}.
070     * @param role the role to check
071     * @return the result of the check
072     */
073    public static boolean isBuiltInRole(final Role role)
074    {
075        return  role.equals( ALL ) || role.equals( ANONYMOUS ) ||
076                role.equals( ASSERTED ) || role.equals( AUTHENTICATED );
077
078    }
079
080    /**
081     * Returns <code>true</code> if the supplied name is identical to the name
082     * of a built-in Role; that is, the value returned by <code>getName()</code>
083     * for built-in Roles {@link #ALL}, {@link #ANONYMOUS},
084     * {@link #ASSERTED}, or {@link #AUTHENTICATED}.
085     * @param name the name to be tested
086     * @return <code>true</code> if the name is reserved; <code>false</code>
087     *         if not
088     */
089    public static boolean isReservedName(final String name)
090    {
091        return  name.equals( ALL.m_name ) ||
092                name.equals( ANONYMOUS.m_name ) || name.equals( ASSERTED.m_name ) ||
093                name.equals( AUTHENTICATED.m_name );
094    }
095
096    /**
097     * Returns a unique hashcode for the Role.
098     * @return the hashcode
099     */
100    public int hashCode()
101    {
102        return m_name.hashCode();
103    }
104
105    /**
106     * Two Role objects are considered equal if their names are identical.
107     * @param obj the object to test
108     * @return <code>true</code> if both objects are of type Role and have identical names
109     * @see java.lang.Object#equals(java.lang.Object)
110     */
111    public boolean equals(final Object obj )
112    {
113        if ( obj == null || !( obj instanceof Role ) ) return false;
114        return m_name.equals( ( (Role) obj ).getName() );
115    }
116
117    /**
118     *  Returns the name of the Principal.
119     * @return the name of the Role
120     */
121    public String getName()
122    {
123        return m_name;
124    }
125
126    /**
127     * Returns a String representation of the role
128     * @return the string representation of the role
129     * @see java.lang.Object#toString()
130     */
131    public String toString()
132    {
133        return "[" + this.getClass().getName() + ": " + m_name + "]";
134    }
135
136}