edu.internet2.middleware.grouper
Class SubjectFinder

java.lang.Object
  edu.internet2.middleware.grouper.SubjectFinder

public class SubjectFinder
extends java.lang.Object

Find I2MI subjects.

Version:

$Id: SubjectFinder.java,v 1.47 2009-12-28 06:08:37 mchyzer Exp $

Author:

blair christensen.

Nested Class Summary

static class

SubjectFinder.RestrictSourceForGroup result to see if source if restricted by group

Constructor Summary

SubjectFinder()

Method Summary

SubjectFinder	assignExceptionIfNotFound(boolean theExceptionIfNotFound) if there should be an exception if not found on one subject to query
SubjectFinder	assignMemberId(java.lang.String theMemberId) assign a member id to search for
SubjectFinder	assignSourceId(java.lang.String theSourceId) assign the source id to search in
SubjectFinder	assignSubjectId(java.lang.String theSubjectId) assign a subjectId to search for
SubjectFinder	assignSubjectIdentifier(java.lang.String theSubjectIdentifier1) assign a subject identifier to search for
SubjectFinder	assignSubjectIdOrIdentifier(java.lang.String theSubjectIdOrIdentifier) assign subject id or identifier to search for
static void	decorateSubjects(GrouperSession grouperSession, java.util.Set<edu.internet2.middleware.subject.Subject> subjects, java.util.Collection<java.lang.String> attributeNamesRequested) decorate subjects based on subject customizer in grouper.properties
static edu.internet2.middleware.subject.Subject	filterSubject(GrouperSession grouperSession, edu.internet2.middleware.subject.Subject subject, java.lang.String filterSubjectsInStemName) filter subjects based on subject customizer in grouper.properties
static java.util.Map<java.lang.String,edu.internet2.middleware.subject.Subject>	filterSubjects(GrouperSession grouperSession, java.util.Map<java.lang.String,edu.internet2.middleware.subject.Subject> subjectMap, java.lang.String filterSubjectsInStemName) filter subjects based on subject customizer in grouper.properties
static java.util.Set<edu.internet2.middleware.subject.Subject>	filterSubjects(GrouperSession grouperSession, java.util.Set<edu.internet2.middleware.subject.Subject> subjects, java.lang.String filterSubjectsInStemName) filter subjects based on subject customizer in grouper.properties
static java.util.Set<edu.internet2.middleware.subject.Subject>	findAll(java.lang.String query) Find all subjects matching the query.
static java.util.Set<edu.internet2.middleware.subject.Subject>	findAll(java.lang.String query, java.util.Set<edu.internet2.middleware.subject.Source> sources) Find all subjects matching the query within the specified Sources.
static java.util.Set<edu.internet2.middleware.subject.Subject>	findAll(java.lang.String query, java.lang.String source) Find all subjects matching the query within the specified Source.
static java.util.Set<edu.internet2.middleware.subject.Subject>	findAllInStem(java.lang.String stemName, java.lang.String query) Find all subjects matching the query, in a certain folder.
static edu.internet2.middleware.subject.Subject	findAllSubject() Get GrouperAll subject.
static edu.internet2.middleware.subject.Subject	findById(java.lang.String id) Deprecated.
static edu.internet2.middleware.subject.Subject	findById(java.lang.String id, boolean exceptionIfNull) Search within all configured sources for subject with identified by id.
static edu.internet2.middleware.subject.Subject	findById(java.lang.String id, java.lang.String type) Deprecated.
static edu.internet2.middleware.subject.Subject	findById(java.lang.String id, java.lang.String type, boolean exceptionIfNull) Deprecated. since type is no longer an identifier... just use id or id/source
static edu.internet2.middleware.subject.Subject	findById(java.lang.String id, java.lang.String type, java.lang.String source) Deprecated.
static edu.internet2.middleware.subject.Subject	findById(java.lang.String id, java.lang.String type, java.lang.String source, boolean exceptionIfNull) Deprecated.
static edu.internet2.middleware.subject.Subject	findByIdAndSource(java.lang.String id, java.lang.String source, boolean exceptionIfNull) Search within all configured sources for subject with identified by id.
static edu.internet2.middleware.subject.Subject	findByIdentifier(java.lang.String id) Deprecated.
static edu.internet2.middleware.subject.Subject	findByIdentifier(java.lang.String id, boolean exceptionIfNotFound) Get a subject by a well-known identifier.
static edu.internet2.middleware.subject.Subject	findByIdentifier(java.lang.String id, java.lang.String type) Deprecated.
static edu.internet2.middleware.subject.Subject	findByIdentifier(java.lang.String id, java.lang.String type, boolean exceptionIfNull) Deprecated. use id or id/source
static edu.internet2.middleware.subject.Subject	findByIdentifier(java.lang.String id, java.lang.String type, java.lang.String source) Deprecated.
static edu.internet2.middleware.subject.Subject	findByIdentifier(java.lang.String id, java.lang.String type, java.lang.String source, boolean exceptionIfNull) Deprecated.
static edu.internet2.middleware.subject.Subject	findByIdentifierAndSource(java.lang.String identifier, java.lang.String source, boolean exceptionIfNull) Get a subject by a well-known identifier, and source.
static java.util.Map<java.lang.String,edu.internet2.middleware.subject.Subject>	findByIdentifiers(java.util.Collection<java.lang.String> identifiers) find subjects by identifiers
static java.util.Map<java.lang.String,edu.internet2.middleware.subject.Subject>	findByIdentifiers(java.util.Collection<java.lang.String> identifiers, java.lang.String source) find subjects by identifiers
static edu.internet2.middleware.subject.Subject	findByIdOrIdentifier(java.lang.String idOrIdentifier, boolean exceptionIfNull) find by id or identifier
static edu.internet2.middleware.subject.Subject	findByIdOrIdentifierAndSource(java.lang.String idOrIdentifier, java.lang.String source, boolean exceptionIfNull) find by id or identifier
static java.util.Map<java.lang.String,edu.internet2.middleware.subject.Subject>	findByIds(java.util.Collection<java.lang.String> ids) find subjects by ids
static java.util.Map<java.lang.String,edu.internet2.middleware.subject.Subject>	findByIds(java.util.Collection<java.lang.String> ids, java.lang.String source) find subjects by ids
static java.util.Map<java.lang.String,edu.internet2.middleware.subject.Subject>	findByIdsOrIdentifiers(java.util.Collection<java.lang.String> idsOrIdentifiers) find subjects by idsOrIdentifiers
static java.util.Map<java.lang.String,edu.internet2.middleware.subject.Subject>	findByIdsOrIdentifiers(java.util.Collection<java.lang.String> idsOrIdentifiers, java.lang.String source) find subjects by idsOrIdentifiers
static edu.internet2.middleware.subject.Subject	findByOptionalArgs(java.lang.String sourceId, java.lang.String subjectId, java.lang.String subjectIdentifier, boolean exceptionIfNotFound) pass in the source (optional), and the id or identifier
static edu.internet2.middleware.subject.Subject	findByPackedSubjectString(java.lang.String subjectString, boolean exceptionIfNotFound) Find a subject by packed subject string.
static java.util.Map<SubjectBean,edu.internet2.middleware.subject.Subject>	findBySubjectBeans(java.util.Collection<SubjectBean> subjectBeans) find by subject beans
static java.util.Set<edu.internet2.middleware.subject.Subject>	findBySubjectsInGroup(GrouperSession grouperSession, java.util.Set<edu.internet2.middleware.subject.Subject> subjects, Group group, Field field, MembershipType membershipType) convert a set of subjects to a set of subject that are in a group
static edu.internet2.middleware.subject.SearchPageResult	findPage(java.lang.String query) Find a page of subjects matching the query.
static edu.internet2.middleware.subject.SearchPageResult	findPage(java.lang.String query, java.util.Set<edu.internet2.middleware.subject.Source> sources) Find a page of subjects matching the query within the specified Sources.
static edu.internet2.middleware.subject.SearchPageResult	findPage(java.lang.String query, java.lang.String source) Find a page of subjects matching the query within the specified Source.
static edu.internet2.middleware.subject.SearchPageResult	findPageInStem(java.lang.String stemName, java.lang.String query) Find a page of subjects matching the query, in a certain folder.
static edu.internet2.middleware.subject.SearchPageResult	findPageInStem(java.lang.String stemName, java.lang.String query, java.util.Set<edu.internet2.middleware.subject.Source> sources) Find a page of subjects matching the query, in a certain folder.
static edu.internet2.middleware.subject.Subject	findRootSubject() Get GrouperSystem subject.
edu.internet2.middleware.subject.Subject	findSubject()
static void	flushCache() flush the cache (e.g. for testing)
static edu.internet2.middleware.subject.Source	getSource(java.lang.String id) try { Source sa = SubjectFinder.getSource(id); } catch (SourceUnavailableException eSU) { // unable to retrieve source }
static java.util.Set<edu.internet2.middleware.subject.Source>	getSources() Set sources = SubjectFinder.getSources();
static GrouperSession	grouperSessionOrRootForSubjectFinder()
static edu.internet2.middleware.subject.Source	internal_getEntitySourceAdapter(boolean failIfError)
static edu.internet2.middleware.subject.Source	internal_getGSA()
static void	internalClearSubjectCustomizerCache() clea the subject customizer cache
static boolean	isUseThreadsBasedOnThreadLocal() if we should use threads when doing searches (if grouper.properties allows)
static void	reset() Reset SubjectResolver.
static SubjectFinder.RestrictSourceForGroup	restrictSourceForGroup(java.lang.String stemName, java.lang.String sourceId)
static SubjectCustomizer	subjectCustomizer() get the subject customizer
static void	useThreads(boolean ifUseThreads) if we should use threads when doing searches (if grouper.properties allows), this must be used in a try/finally

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SubjectFinder

public SubjectFinder()

Method Detail

assignSubjectId

public SubjectFinder assignSubjectId(java.lang.String theSubjectId)

assign a subjectId to search for

Parameters:

theSubjectId -

Returns:

this for chaining

assignSourceId

public SubjectFinder assignSourceId(java.lang.String theSourceId)

assign the source id to search in

Parameters:

theSourceId -

Returns:

this for chaining

assignSubjectIdentifier

public SubjectFinder assignSubjectIdentifier(java.lang.String theSubjectIdentifier1)

assign a subject identifier to search for

Parameters:

theSubjectIdentifier1 -

Returns:

this for chaining

assignSubjectIdOrIdentifier

public SubjectFinder assignSubjectIdOrIdentifier(java.lang.String theSubjectIdOrIdentifier)

assign subject id or identifier to search for

Parameters:

theSubjectIdOrIdentifier -

Returns:

this for chaining

assignMemberId

public SubjectFinder assignMemberId(java.lang.String theMemberId)

assign a member id to search for

Parameters:

theMemberId -

Returns:

this for chaining

assignExceptionIfNotFound

public SubjectFinder assignExceptionIfNotFound(boolean theExceptionIfNotFound)

if there should be an exception if not found on one subject to query

Parameters:

theExceptionIfNotFound -

Returns:

this for chaining

findSubject

public edu.internet2.middleware.subject.Subject findSubject()

grouperSessionOrRootForSubjectFinder

public static GrouperSession grouperSessionOrRootForSubjectFinder()

Returns:

session

useThreads

public static void useThreads(boolean ifUseThreads)

if we should use threads when doing searches (if grouper.properties allows), this must be used in a try/finally

Parameters:

ifUseThreads -

isUseThreadsBasedOnThreadLocal

public static boolean isUseThreadsBasedOnThreadLocal()

if we should use threads when doing searches (if grouper.properties allows)

Returns:

isUseThreadsBasedOnThreadLocal

findByIdOrIdentifier

public static edu.internet2.middleware.subject.Subject findByIdOrIdentifier(java.lang.String idOrIdentifier,
                                                                            boolean exceptionIfNull)
                                                                     throws edu.internet2.middleware.subject.SubjectNotFoundException,
                                                                            edu.internet2.middleware.subject.SubjectNotUniqueException

find by id or identifier

Parameters:

idOrIdentifier -

exceptionIfNull - if SubjectNotFoundException or null

Returns:

the subject

Throws:

edu.internet2.middleware.subject.SubjectNotFoundException

edu.internet2.middleware.subject.SubjectNotUniqueException

findByOptionalArgs

public static edu.internet2.middleware.subject.Subject findByOptionalArgs(java.lang.String sourceId,
                                                                          java.lang.String subjectId,
                                                                          java.lang.String subjectIdentifier,
                                                                          boolean exceptionIfNotFound)

pass in the source (optional), and the id or identifier

Parameters:

sourceId -

subjectId -

subjectIdentifier -

exceptionIfNotFound -

Returns:

the subject or null

findByIdOrIdentifierAndSource

public static edu.internet2.middleware.subject.Subject findByIdOrIdentifierAndSource(java.lang.String idOrIdentifier,
                                                                                     java.lang.String source,
                                                                                     boolean exceptionIfNull)
                                                                              throws edu.internet2.middleware.subject.SubjectNotFoundException,
                                                                                     edu.internet2.middleware.subject.SubjectNotUniqueException

find by id or identifier

Parameters:

idOrIdentifier -

source -

exceptionIfNull - if SubjectNotFoundException or null

Returns:

the subject

Throws:

edu.internet2.middleware.subject.SubjectNotFoundException

edu.internet2.middleware.subject.SubjectNotUniqueException

findById

@Deprecated
public static edu.internet2.middleware.subject.Subject findById(java.lang.String id)
                                                         throws edu.internet2.middleware.subject.SubjectNotFoundException,
                                                                edu.internet2.middleware.subject.SubjectNotUniqueException

Deprecated.

Search within all configured sources for subject with identified by id.

 try {
   Subject subj = SubjectFinder.findById(subjectID);
 }
 catch (SubjectNotFoundException eSNF)  {
   // Subject not found
 }
 catch (SubjectNotUniqueException eSNU) {
   // Subject not unique
 }
  

Parameters:

id - Subject ID

Returns:

A Subject object

Throws:

edu.internet2.middleware.subject.SubjectNotFoundException

edu.internet2.middleware.subject.SubjectNotUniqueException

findById

public static edu.internet2.middleware.subject.Subject findById(java.lang.String id,
                                                                boolean exceptionIfNull)
                                                         throws edu.internet2.middleware.subject.SubjectNotFoundException,
                                                                edu.internet2.middleware.subject.SubjectNotUniqueException

Search within all configured sources for subject with identified by id.

 try {
   Subject subj = SubjectFinder.findById(subjectID);
 }
 catch (SubjectNotFoundException eSNF)  {
   // Subject not found
 }
 catch (SubjectNotUniqueException eSNU) {
   // Subject not unique
 }
  

Parameters:

id - Subject ID

exceptionIfNull -

Returns:

A Subject object

Throws:

edu.internet2.middleware.subject.SubjectNotFoundException

edu.internet2.middleware.subject.SubjectNotUniqueException

findByIdAndSource

public static edu.internet2.middleware.subject.Subject findByIdAndSource(java.lang.String id,
                                                                         java.lang.String source,
                                                                         boolean exceptionIfNull)
                                                                  throws edu.internet2.middleware.subject.SubjectNotFoundException,
                                                                         edu.internet2.middleware.subject.SubjectNotUniqueException

Search within all configured sources for subject with identified by id.

 try {
   Subject subj = SubjectFinder.findByIdAndSource(subjectID, source, true);
 }
 catch (SubjectNotFoundException eSNF)  {
   // Subject not found
 }
 catch (SubjectNotUniqueException eSNU) {
   // Subject not unique
 }
  

Parameters:

id - Subject ID

source - is the source to check in

exceptionIfNull -

Returns:

A Subject object

Throws:

edu.internet2.middleware.subject.SubjectNotFoundException

edu.internet2.middleware.subject.SubjectNotUniqueException

findBySubjectBeans

public static java.util.Map<SubjectBean,edu.internet2.middleware.subject.Subject> findBySubjectBeans(java.util.Collection<SubjectBean> subjectBeans)

find by subject beans

Parameters:

subjectBeans -

Returns:

the subjects

findByIds

public static java.util.Map<java.lang.String,edu.internet2.middleware.subject.Subject> findByIds(java.util.Collection<java.lang.String> ids)

find subjects by ids

Parameters:

ids -

Returns:

the map of id to subject. If a subject is not found, it will not be in the result

findByIdsOrIdentifiers

public static java.util.Map<java.lang.String,edu.internet2.middleware.subject.Subject> findByIdsOrIdentifiers(java.util.Collection<java.lang.String> idsOrIdentifiers)

find subjects by idsOrIdentifiers

Parameters:

idsOrIdentifiers -

Returns:

the map of id or identifier to subject. If a subject is not found, it will not be in the result

findByIdsOrIdentifiers

public static java.util.Map<java.lang.String,edu.internet2.middleware.subject.Subject> findByIdsOrIdentifiers(java.util.Collection<java.lang.String> idsOrIdentifiers,
                                                                                                              java.lang.String source)

find subjects by idsOrIdentifiers

Parameters:

idsOrIdentifiers -

source -

Returns:

the map of id or identifier to subject. If a subject is not found, it will not be in the result

findByIdentifiers

public static java.util.Map<java.lang.String,edu.internet2.middleware.subject.Subject> findByIdentifiers(java.util.Collection<java.lang.String> identifiers)

find subjects by identifiers

Parameters:

identifiers -

Returns:

the map of identifier to subject. If a subject is not found, it will not be in the result

flushCache

public static void flushCache()

flush the cache (e.g. for testing)

findById

@Deprecated
public static edu.internet2.middleware.subject.Subject findById(java.lang.String id,
                                                                           java.lang.String type)
                                                         throws edu.internet2.middleware.subject.SubjectNotFoundException,
                                                                edu.internet2.middleware.subject.SubjectNotUniqueException

Deprecated.

Search within all configured sources providing type for subject with identified by id.

 try {
   Subject subj = SubjectFinder.findById(subjectID, type);
 }
 catch (SubjectNotFoundException eSNF)  {
   // Subject not found
 }
 catch (SubjectNotUniqueException eSNU) {
   // Subject not unique
 }
  

Parameters:

id - Subject ID

type - Subject type.

Returns:

A Subject object

Throws:

edu.internet2.middleware.subject.SubjectNotFoundException

edu.internet2.middleware.subject.SubjectNotUniqueException

findById

@Deprecated
public static edu.internet2.middleware.subject.Subject findById(java.lang.String id,
                                                                           java.lang.String type,
                                                                           java.lang.String source)
                                                         throws edu.internet2.middleware.subject.SourceUnavailableException,
                                                                edu.internet2.middleware.subject.SubjectNotFoundException,
                                                                edu.internet2.middleware.subject.SubjectNotUniqueException

Deprecated.

Search for subject by id, type and source.

 try {
   Subject subj = SubjectFinder.findById(id, type, source);
 }
 catch (SourceUnavailableException eSU) {
   // unable to query source
 }
 catch (SubjectNotFoundException eSNF) {
   // subject not found
 }
  

Parameters:

id - Subject ID

type - Subject type.

source - Subject source.

Returns:

Matching subject.

Throws:

edu.internet2.middleware.subject.SourceUnavailableException

edu.internet2.middleware.subject.SubjectNotFoundException

edu.internet2.middleware.subject.SubjectNotUniqueException

findByIdentifier

@Deprecated
public static edu.internet2.middleware.subject.Subject findByIdentifier(java.lang.String id)
                                                                 throws edu.internet2.middleware.subject.SubjectNotFoundException,
                                                                        edu.internet2.middleware.subject.SubjectNotUniqueException

Deprecated.

Get a subject by a well-known identifier.

 try {
   Subject subj = SubjectFinder.findByIdentifier(identifier);
 }
 catch (SubjectNotFoundException eSNF)  {
   // Subject not found
 }
 catch (SubjectNotUniqueException eSNU) {
   // Subject not unique
 }
  

Parameters:

id - Subject identifier.

Returns:

A Subject object

Throws:

edu.internet2.middleware.subject.SubjectNotFoundException

edu.internet2.middleware.subject.SubjectNotUniqueException

findByIdentifier

@Deprecated
public static edu.internet2.middleware.subject.Subject findByIdentifier(java.lang.String id,
                                                                                   java.lang.String type)
                                                                 throws edu.internet2.middleware.subject.SubjectNotFoundException,
                                                                        edu.internet2.middleware.subject.SubjectNotUniqueException

Deprecated.

Get a subject by a well-known identifier and the specified type.

 try {
   Subject subj = SubjectFinder.findByIdentifier(identifier, type);
 }
 catch (SubjectNotFoundException eSNF)  {
   // subject not found
 }
 catch (SubjectNotUniqueException eSNU) {
   // subject not found
 }
  

Parameters:

id - Subject identifier.

type - Subject type.

Returns:

A Subject object

Throws:

edu.internet2.middleware.subject.SubjectNotFoundException

edu.internet2.middleware.subject.SubjectNotUniqueException

findByIdentifier

@Deprecated
public static edu.internet2.middleware.subject.Subject findByIdentifier(java.lang.String id,
                                                                                   java.lang.String type,
                                                                                   java.lang.String source)
                                                                 throws edu.internet2.middleware.subject.SourceUnavailableException,
                                                                        edu.internet2.middleware.subject.SubjectNotFoundException,
                                                                        edu.internet2.middleware.subject.SubjectNotUniqueException

Deprecated.

Get a subject by a well-known identifier, type and source.

NOTE: This method does not perform any caching.

 try {
   Subject subj = SubjectFinder.findByIdentifier(id, type, source);
 }
 catch (SubjectNotFoundException e) {
   // Subject not found
 }
  

Parameters:

id - Well-known identifier.

type - Subject type.

source - Source adapter to search.

Returns:

A Subject object

Throws:

edu.internet2.middleware.subject.SourceUnavailableException

edu.internet2.middleware.subject.SubjectNotFoundException

edu.internet2.middleware.subject.SubjectNotUniqueException

findAll

public static java.util.Set<edu.internet2.middleware.subject.Subject> findAll(java.lang.String query)

Find all subjects matching the query.

The query string specification is currently unique to each subject source adapter. Queries may not work or may lead to erratic results across different source adapters. Consult the documentation for each source adapter for more information on the query language supported by each adapter.

NOTE: This method does not perform any caching.

 // Find all subjects matching the given query string.
 Set subjects = SubjectFinder.findAll(query);
 

Parameters:

query - Subject query string.

Returns:

A Set of Subject objects.

Throws:

edu.internet2.middleware.subject.SubjectTooManyResults - if more results than configured

findAllInStem

public static java.util.Set<edu.internet2.middleware.subject.Subject> findAllInStem(java.lang.String stemName,
                                                                                    java.lang.String query)

Find all subjects matching the query, in a certain folder. If there are rules restricting subjects, then dont search those folders

The query string specification is currently unique to each subject source adapter. Queries may not work or may lead to erratic results across different source adapters. Consult the documentation for each source adapter for more information on the query language supported by each adapter.

NOTE: This method does not perform any caching.

 // Find all subjects matching the given query string.
 Set subjects = SubjectFinder.findAll(query);
 

Parameters:

stemName - stem name to search in

query - Subject query string.

Returns:

A Set of Subject objects.

Throws:

edu.internet2.middleware.subject.SubjectTooManyResults - if more results than configured

findAll

public static java.util.Set<edu.internet2.middleware.subject.Subject> findAll(java.lang.String query,
                                                                              java.lang.String source)
                                                                       throws edu.internet2.middleware.subject.SourceUnavailableException

Find all subjects matching the query within the specified Source.

NOTE: This method does not perform any caching.

 try {
   Set subjects = SubjectFinder.findAll(query, source);
 }
 catch (SourceUnavailableException eSU) {
   // unable to query source
 }
  

Parameters:

query - Subject query string.r.

source - Source adapter to search.

Returns:

A Set of Subjects.

Throws:

edu.internet2.middleware.subject.SourceUnavailableException

findAll

public static java.util.Set<edu.internet2.middleware.subject.Subject> findAll(java.lang.String query,
                                                                              java.util.Set<edu.internet2.middleware.subject.Source> sources)
                                                                       throws edu.internet2.middleware.subject.SourceUnavailableException

Find all subjects matching the query within the specified Sources.

NOTE: This method does not perform any caching.

 try {
   Set subjects = SubjectFinder.findAll(query, sources);
 }
 catch (SourceUnavailableException eSU) {
   // unable to query source
 }
  

Parameters:

query - Subject query string.

sources - Source adapters to search.

Returns:

A Set of Subjects.

Throws:

edu.internet2.middleware.subject.SourceUnavailableException

findAllSubject

public static edu.internet2.middleware.subject.Subject findAllSubject()
                                                               throws GrouperException

Get GrouperAll subject.

 Subject all = SubjectFinder.findAllSubject();
  

Returns:

The GrouperAll Subject Get GrouperAll subject.

 Subject all = SubjectFinder.findAllSubject();
  

Throws:

GrouperException - if unable to retrieve GrouperAll.

Since:

1.1.0

findRootSubject

public static edu.internet2.middleware.subject.Subject findRootSubject()
                                                                throws GrouperException

Get GrouperSystem subject.

 Subject root = SubjectFinder.findRootSubject();
  

Returns:

The GrouperSystem subject.

Throws:

GrouperException - if unable to retrieve GrouperSystem.

Since:

1.1.0

getSource

public static edu.internet2.middleware.subject.Source getSource(java.lang.String id)
                                                         throws java.lang.IllegalArgumentException,
                                                                edu.internet2.middleware.subject.SourceUnavailableException

 try {
   Source sa = SubjectFinder.getSource(id);
 }
 catch (SourceUnavailableException eSU) {
   // unable to retrieve source
 }
 

Parameters:

id -

Returns:

Source identified by id.

Throws:

java.lang.IllegalArgumentException - if id is null.

edu.internet2.middleware.subject.SourceUnavailableException - if unable to retrieve source.

getSources

public static java.util.Set<edu.internet2.middleware.subject.Source> getSources()

 Set sources = SubjectFinder.getSources();
 

Returns:

Set of all Source adapters.

internal_getGSA

public static edu.internet2.middleware.subject.Source internal_getGSA()

Returns:

source

Since:

1.2.0

internal_getEntitySourceAdapter

public static edu.internet2.middleware.subject.Source internal_getEntitySourceAdapter(boolean failIfError)

Parameters:

failIfError -

Returns:

source

Since:

2.1.0

reset

public static void reset()

Reset SubjectResolver.

Since:

1.2.1

findById

@Deprecated
public static edu.internet2.middleware.subject.Subject findById(java.lang.String id,
                                                                           java.lang.String type,
                                                                           boolean exceptionIfNull)
                                                         throws edu.internet2.middleware.subject.SubjectNotFoundException,
                                                                edu.internet2.middleware.subject.SubjectNotUniqueException

Deprecated. since type is no longer an identifier... just use id or id/source

Search within all configured sources providing type for subject with identified by id.

 try {
   Subject subj = SubjectFinder.findById(subjectID, type);
 }
 catch (SubjectNotFoundException eSNF)  {
   // Subject not found
 }
 catch (SubjectNotUniqueException eSNU) {
   // Subject not unique
 }
  

Parameters:

id - Subject ID

type - Subject type.

exceptionIfNull -

Returns:

A Subject object

Throws:

edu.internet2.middleware.subject.SubjectNotFoundException

edu.internet2.middleware.subject.SubjectNotUniqueException

findById

@Deprecated
public static edu.internet2.middleware.subject.Subject findById(java.lang.String id,
                                                                           java.lang.String type,
                                                                           java.lang.String source,
                                                                           boolean exceptionIfNull)
                                                         throws edu.internet2.middleware.subject.SourceUnavailableException,
                                                                edu.internet2.middleware.subject.SubjectNotFoundException,
                                                                edu.internet2.middleware.subject.SubjectNotUniqueException

Deprecated.

Search for subject by id, type and source.

 try {
   Subject subj = SubjectFinder.findById(id, type, source);
 }
 catch (SourceUnavailableException eSU) {
   // unable to query source
 }
 catch (SubjectNotFoundException eSNF) {
   // subject not found
 }
  

Parameters:

id - Subject ID

type - Subject type. If blank dont consider type

source - Subject source.

exceptionIfNull -

Returns:

Matching subject.

Throws:

edu.internet2.middleware.subject.SourceUnavailableException

edu.internet2.middleware.subject.SubjectNotFoundException

edu.internet2.middleware.subject.SubjectNotUniqueException

findByIdentifier

public static edu.internet2.middleware.subject.Subject findByIdentifier(java.lang.String id,
                                                                        boolean exceptionIfNotFound)
                                                                 throws edu.internet2.middleware.subject.SubjectNotFoundException,
                                                                        edu.internet2.middleware.subject.SubjectNotUniqueException

Get a subject by a well-known identifier.

 try {
   Subject subj = SubjectFinder.findByIdentifier(identifier);
 }
 catch (SubjectNotFoundException eSNF)  {
   // Subject not found
 }
 catch (SubjectNotUniqueException eSNU) {
   // Subject not unique
 }
  

Parameters:

id - Subject identifier.

exceptionIfNotFound -

Returns:

A Subject object

Throws:

edu.internet2.middleware.subject.SubjectNotFoundException

edu.internet2.middleware.subject.SubjectNotUniqueException

findByIdentifier

@Deprecated
public static edu.internet2.middleware.subject.Subject findByIdentifier(java.lang.String id,
                                                                                   java.lang.String type,
                                                                                   boolean exceptionIfNull)
                                                                 throws edu.internet2.middleware.subject.SubjectNotFoundException,
                                                                        edu.internet2.middleware.subject.SubjectNotUniqueException

Deprecated. use id or id/source

Get a subject by a well-known identifier and the specified type.

 try {
   Subject subj = SubjectFinder.findByIdentifier(identifier, type);
 }
 catch (SubjectNotFoundException eSNF)  {
   // subject not found
 }
 catch (SubjectNotUniqueException eSNU) {
   // subject not found
 }
  

Parameters:

id - Subject identifier.

type - Subject type.

exceptionIfNull -

Returns:

A Subject object

Throws:

edu.internet2.middleware.subject.SubjectNotFoundException

edu.internet2.middleware.subject.SubjectNotUniqueException

findByIdentifier

@Deprecated
public static edu.internet2.middleware.subject.Subject findByIdentifier(java.lang.String id,
                                                                                   java.lang.String type,
                                                                                   java.lang.String source,
                                                                                   boolean exceptionIfNull)
                                                                 throws edu.internet2.middleware.subject.SourceUnavailableException,
                                                                        edu.internet2.middleware.subject.SubjectNotFoundException,
                                                                        edu.internet2.middleware.subject.SubjectNotUniqueException

Deprecated.

Get a subject by a well-known identifier, type and source.

NOTE: This method does not perform any caching.

 try {
   Subject subj = SubjectFinder.findByIdentifier(id, type, source);
 }
 catch (SubjectNotFoundException e) {
   // Subject not found
 }
  

Parameters:

id - Well-known identifier.

type - Subject type.

source - Source adapter to search.

exceptionIfNull -

Returns:

A Subject object

Throws:

edu.internet2.middleware.subject.SourceUnavailableException

edu.internet2.middleware.subject.SubjectNotFoundException

edu.internet2.middleware.subject.SubjectNotUniqueException

findBySubjectsInGroup

public static java.util.Set<edu.internet2.middleware.subject.Subject> findBySubjectsInGroup(GrouperSession grouperSession,
                                                                                            java.util.Set<edu.internet2.middleware.subject.Subject> subjects,
                                                                                            Group group,
                                                                                            Field field,
                                                                                            MembershipType membershipType)

convert a set of subjects to a set of subject that are in a group

Parameters:

grouperSession -

subjects - to convert to members

group - that subjects must be in

field - that they must be in in the group (null will default to eh members list

membershipType - that they must be in in the group or null for any

Returns:

the subjects in the group (never null)

findByIdentifierAndSource

public static edu.internet2.middleware.subject.Subject findByIdentifierAndSource(java.lang.String identifier,
                                                                                 java.lang.String source,
                                                                                 boolean exceptionIfNull)
                                                                          throws edu.internet2.middleware.subject.SourceUnavailableException,
                                                                                 edu.internet2.middleware.subject.SubjectNotFoundException,
                                                                                 edu.internet2.middleware.subject.SubjectNotUniqueException

Get a subject by a well-known identifier, and source.

NOTE: This method does not perform any caching.

 try {
   Subject subj = SubjectFinder.findByIdentifierAndSource(id, source, true);
 }
 catch (SubjectNotFoundException e) {
   // Subject not found
 }
  

Parameters:

identifier - Well-known identifier.

source - Source adapter to search.

exceptionIfNull -

Returns:

A Subject object

Throws:

edu.internet2.middleware.subject.SourceUnavailableException

edu.internet2.middleware.subject.SubjectNotFoundException

edu.internet2.middleware.subject.SubjectNotUniqueException

findByPackedSubjectString

public static edu.internet2.middleware.subject.Subject findByPackedSubjectString(java.lang.String subjectString,
                                                                                 boolean exceptionIfNotFound)

 Find a subject by packed subject string.  This could be a four colons then subjectId or six colons then a subjectIdentifier, or
 a source then four colons, then subjectId, or a source then six colons then a subjectIdentifier. 
 or a subjectIdOrIdentifier, or a source, then eight colons, then a subjectIdentifier e.g.
 subjectIdOrIdentifier
 sourceId::::subjectId
 ::::subjectId
 sourceId::::::subjectIdentifier
 ::::::subjectIdentifier
 sourceId::::::::subjectIdOrIdentifier
 ::::::::subjectIdOrIdentifier
 

Parameters:

subjectString -

exceptionIfNotFound -

Returns:

the subject

restrictSourceForGroup

public static SubjectFinder.RestrictSourceForGroup restrictSourceForGroup(java.lang.String stemName,
                                                                          java.lang.String sourceId)

Parameters:

sourceId -

stemName -

Returns:

if restricted and to what extent

findPage

public static edu.internet2.middleware.subject.SearchPageResult findPage(java.lang.String query)

Find a page of subjects matching the query.

The query string specification is currently unique to each subject source adapter. Queries may not work or may lead to erratic results across different source adapters. Consult the documentation for each source adapter for more information on the query language supported by each adapter.

NOTE: This method does not perform any caching.

 // Find all subjects matching the given query string.
 SearchPageResult subjects = SubjectFinder.findPage(query);
 

Parameters:

query - Subject query string.

Returns:

A Set of Subject objects and if there are too many.

Throws:

edu.internet2.middleware.subject.SubjectTooManyResults - if more results than configured

findPage

public static edu.internet2.middleware.subject.SearchPageResult findPage(java.lang.String query,
                                                                         java.util.Set<edu.internet2.middleware.subject.Source> sources)
                                                                  throws edu.internet2.middleware.subject.SourceUnavailableException

Find a page of subjects matching the query within the specified Sources.

NOTE: This method does not perform any caching.

 try {
   SearchPageResult subjects = SubjectFinder.findPage(query, sources);
 }
 catch (SourceUnavailableException eSU) {
   // unable to query source
 }
  

Parameters:

query - Subject query string.

sources - Source adapters to search.

Returns:

A Set of Subjects and if there are too many.

Throws:

edu.internet2.middleware.subject.SourceUnavailableException

findPage

public static edu.internet2.middleware.subject.SearchPageResult findPage(java.lang.String query,
                                                                         java.lang.String source)
                                                                  throws edu.internet2.middleware.subject.SourceUnavailableException

Find a page of subjects matching the query within the specified Source.

NOTE: This method does not perform any caching.

 try {
   Set subjects = SubjectFinder.findPage(query, source);
 }
 catch (SourceUnavailableException eSU) {
   // unable to query source
 }
  

Parameters:

query - Subject query string.r.

source - Source adapter to search.

Returns:

A Set of Subjects and if too many.

Throws:

edu.internet2.middleware.subject.SourceUnavailableException

findPageInStem

public static edu.internet2.middleware.subject.SearchPageResult findPageInStem(java.lang.String stemName,
                                                                               java.lang.String query)

Find a page of subjects matching the query, in a certain folder. If there are rules restricting subjects, then dont search those folders

The query string specification is currently unique to each subject source adapter. Queries may not work or may lead to erratic results across different source adapters. Consult the documentation for each source adapter for more information on the query language supported by each adapter.

NOTE: This method does not perform any caching.

 // Find all subjects matching the given query string.
 Set subjects = SubjectFinder.findAll(query);
 

Parameters:

stemName - stem name to search in

query - Subject query string.

Returns:

A Set of Subject objects.

Throws:

edu.internet2.middleware.subject.SubjectTooManyResults - if more results than configured

findPageInStem

public static edu.internet2.middleware.subject.SearchPageResult findPageInStem(java.lang.String stemName,
                                                                               java.lang.String query,
                                                                               java.util.Set<edu.internet2.middleware.subject.Source> sources)

Find a page of subjects matching the query, in a certain folder. If there are rules restricting subjects, then dont search those folders

The query string specification is currently unique to each subject source adapter. Queries may not work or may lead to erratic results across different source adapters. Consult the documentation for each source adapter for more information on the query language supported by each adapter.

NOTE: This method does not perform any caching.

 // Find all subjects matching the given query string.
 Set subjects = SubjectFinder.findAll(query);
 

Parameters:

stemName - stem name to search in

query - Subject query string.

Returns:

A Set of Subject objects.

Throws:

edu.internet2.middleware.subject.SubjectTooManyResults - if more results than configured

findByIdentifiers

public static java.util.Map<java.lang.String,edu.internet2.middleware.subject.Subject> findByIdentifiers(java.util.Collection<java.lang.String> identifiers,
                                                                                                         java.lang.String source)

find subjects by identifiers

Parameters:

identifiers -

source -

Returns:

the map of identifier to subject. If a subject is not found, it will not be in the result

findByIds

public static java.util.Map<java.lang.String,edu.internet2.middleware.subject.Subject> findByIds(java.util.Collection<java.lang.String> ids,
                                                                                                 java.lang.String source)

find subjects by ids

Parameters:

ids -

source -

Returns:

the map of id to subject. If a subject is not found, it will not be in the result

decorateSubjects

public static void decorateSubjects(GrouperSession grouperSession,
                                    java.util.Set<edu.internet2.middleware.subject.Subject> subjects,
                                    java.util.Collection<java.lang.String> attributeNamesRequested)

decorate subjects based on subject customizer in grouper.properties

Parameters:

grouperSession -

subjects -

attributeNamesRequested -

filterSubjects

public static java.util.Map<java.lang.String,edu.internet2.middleware.subject.Subject> filterSubjects(GrouperSession grouperSession,
                                                                                                      java.util.Map<java.lang.String,edu.internet2.middleware.subject.Subject> subjectMap,
                                                                                                      java.lang.String filterSubjectsInStemName)

filter subjects based on subject customizer in grouper.properties

Parameters:

grouperSession -

subjectMap - is map os subject id to subject

filterSubjectsInStemName -

attributeNamesRequested -

Returns:

subject map

filterSubjects

public static java.util.Set<edu.internet2.middleware.subject.Subject> filterSubjects(GrouperSession grouperSession,
                                                                                     java.util.Set<edu.internet2.middleware.subject.Subject> subjects,
                                                                                     java.lang.String filterSubjectsInStemName)

filter subjects based on subject customizer in grouper.properties

Parameters:

grouperSession -

subjects -

filterSubjectsInStemName -

attributeNamesRequested -

Returns:

subjects

filterSubject

public static edu.internet2.middleware.subject.Subject filterSubject(GrouperSession grouperSession,
                                                                     edu.internet2.middleware.subject.Subject subject,
                                                                     java.lang.String filterSubjectsInStemName)

filter subjects based on subject customizer in grouper.properties

Parameters:

grouperSession -

subject -

filterSubjectsInStemName -

attributeNamesRequested -

Returns:

subjects

internalClearSubjectCustomizerCache

public static void internalClearSubjectCustomizerCache()

clea the subject customizer cache

subjectCustomizer

public static SubjectCustomizer subjectCustomizer()

get the subject customizer

Returns:

subject customizer or null