    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    @Override
    122    public String getName()
    123    {
    124        return m_name;
    125    }
    126
    127    /**
    128     * Returns a String representation of the role
    129     * @return the string representation of the role
    130     * @see java.lang.Object#toString()
    131     */
    132    public String toString()
    133    {
    134        return "[" + this.getClass().getName() + ": " + m_name + "]";
    135    }
    136
    137}