org.apache.jackrabbit.api.security.principal.PrincipalManager Maven / Gradle / Ivy
/*
* 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.principal;
import java.security.Principal;
import java.security.acl.Group;
/**
* This interface defines the principal manager which is the clients view on
* all principals known to the repository. Each principal manager is bound to
* a session and is restricted by the respective access control. The principal
* manager in addition provides basic search facilities.
*
* A {@link Principal} is an object used to connect
* to any kind of security mechanism. Example for this are the
* {@link javax.security.auth.spi.LoginModule login modules} that use principals
* to process the login procedure.
* A principal can be a member of a {@link Group}. A
* group is a principal itself and can therefore be a member of a group again.
*
* Please note the following security considerations that need to be respected
* when implementing the PrincipalManager: All principals returned by this
* manager as well as {@link Group#members()} must respect access restrictions
* that may be present for the Session this manager has been built
* for. The same applies for {@link #getGroupMembership(Principal)}.
*/
public interface PrincipalManager {
/**
* Filter flag indicating that only Principals that do NOT
* represent a {@link java.security.acl.Group group} should be searched
* and returned.
*/
int SEARCH_TYPE_NOT_GROUP = 1;
/**
* Filter flag indicating that only Principals that represent
* a {@link java.security.acl.Group group} of Principals should be searched
* and returned.
*/
int SEARCH_TYPE_GROUP = 2;
/**
* Filter flag indicating that all Principals should be search
* irrespective whether they represent a group of Principals or not.
*/
int SEARCH_TYPE_ALL = 3;
/**
* Checks if the principal with the given name is known to this manager
* (in respect to the sessions access rights). If this method returns
* true then the following expression evaluates to true
* as well: PrincipalManager.getPrincipal(name).getName().equals(name)
*
* @param principalName the name of the principal to check
* @return return true if the principal with this name is known
* to this manager; false otherwise.
*/
boolean hasPrincipal(String principalName);
/**
* Returns the principal with the given name if is known to this manager
* (with respect to the sessions access rights).
* Please note that due to security reasons Group principals will only
* reveal those members that are visible to the Session this
* PrincipalManager has been built for.
*
* @param principalName the name of the principal to retrieve
* @return return the requested principal or null if a
* principal with the given name does not exist or is not accessible
* for the editing session.
*/
Principal getPrincipal(String principalName);
/**
* Gets the principals matching a simple filter expression applied against
* the {@link Principal#getName() principal name}.
* TODO: define the filter expression.
* An implementation may limit the number of principals returned.
* If there are no matching principals, an empty iterator is returned.
*
* @param simpleFilter
* @return a PrincipalIterator over the Principals
* matching the given filter.
*/
PrincipalIterator findPrincipals(String simpleFilter);
/**
* Gets the principals matching a simple filter expression applied against
* the {@link Principal#getName() principal name} AND the specified search
* type.
* TODO: define the filter expression.
* An implementation may limit the number of principals returned.
* If there are no matching principals, an empty iterator is returned.
*
* @param simpleFilter
* @param searchType Any of the following constants:
*
* - {@link PrincipalManager#SEARCH_TYPE_ALL}
* - {@link PrincipalManager#SEARCH_TYPE_GROUP}
* - {@link PrincipalManager#SEARCH_TYPE_NOT_GROUP}
*
* @return a PrincipalIterator over the Principals
* matching the given filter and search type.
*/
PrincipalIterator findPrincipals(String simpleFilter, int searchType);
/**
* Returns all Principals matching the specified search type.
*
* @param searchType Any of the following constants:
*
* - {@link PrincipalManager#SEARCH_TYPE_ALL}
* - {@link PrincipalManager#SEARCH_TYPE_GROUP}
* - {@link PrincipalManager#SEARCH_TYPE_NOT_GROUP}
*
* @return a PrincipalIterator over all the Principals
* matching the given search type.
*/
PrincipalIterator getPrincipals(int searchType);
/**
* Returns an iterator over all group principals for which the given
* principal is either direct or indirect member of.
*
* Example:
* If Principal P is member of Group A, and Group A is member of
* Group B, this method will return Principal A and Principal B.
*
* @param principal the principal to return it's membership from.
* @return an iterator returning all groups the given principal is member of.
*/
PrincipalIterator getGroupMembership(Principal principal);
/**
* Returns the Principal which is implicitly applied to
* every subject.
*
* @return the 'everyone' principal
*/
Principal getEveryone();
}