edu.internet2.middleware.grouper
Class SubjectFinder

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

public class SubjectFinder
extends 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
static Set<Subject> findAll(String query)
          Find all subjects matching the query.
static Set<Subject> findAll(String query, Set<Source> sources)
          Find all subjects matching the query within the specified Sources.
static Set<Subject> findAll(String query, String source)
          Find all subjects matching the query within the specified Source.
static Set<Subject> findAllInStem(String stemName, String query)
          Find all subjects matching the query, in a certain folder.
static Subject findAllSubject()
          Get GrouperAll subject.
static Subject findById(String id)
          Deprecated.  
static Subject findById(String id, boolean exceptionIfNull)
          Search within all configured sources for subject with identified by id.
static Subject findById(String id, String type)
          Deprecated.  
static Subject findById(String id, String type, boolean exceptionIfNull)
          Deprecated. since type is no longer an identifier... just use id or id/source
static Subject findById(String id, String type, String source)
          Deprecated.  
static Subject findById(String id, String type, String source, boolean exceptionIfNull)
          Deprecated. 
static Subject findByIdAndSource(String id, String source, boolean exceptionIfNull)
          Search within all configured sources for subject with identified by id.
static Subject findByIdentifier(String id)
          Deprecated.  
static Subject findByIdentifier(String id, boolean exceptionIfNotFound)
          Get a subject by a well-known identifier.
static Subject findByIdentifier(String id, String type)
          Deprecated.  
static Subject findByIdentifier(String id, String type, boolean exceptionIfNull)
          Deprecated. use id or id/source
static Subject findByIdentifier(String id, String type, String source)
          Deprecated.  
static Subject findByIdentifier(String id, String type, String source, boolean exceptionIfNull)
          Deprecated. 
static Subject findByIdentifierAndSource(String identifier, String source, boolean exceptionIfNull)
          Get a subject by a well-known identifier, and source.
static Subject findByIdOrIdentifier(String idOrIdentifier, boolean exceptionIfNull)
          find by id or identifier
static Subject findByIdOrIdentifierAndSource(String idOrIdentifier, String source, boolean exceptionIfNull)
          find by id or identifier
static Subject findByOptionalArgs(String sourceId, String subjectId, String subjectIdentifier, boolean exceptionIfNotFound)
          pass in the source (optional), and the id or identifier
static Subject findByPackedSubjectString(String subjectString, boolean exceptionIfNotFound)
           Find a subject by packed subject string.
static Set<Subject> findBySubjectsInGroup(GrouperSession grouperSession, Set<Subject> subjects, Group group, Field field, MembershipType membershipType)
          convert a set of subjects to a set of subject that are in a group
static Subject findRootSubject()
          Get GrouperSystem subject.
static void flushCache()
          flush the cache (e.g.
static Source getSource(String id)
          
 try {
   Source sa = SubjectFinder.getSource(id);
 }
 catch (SourceUnavailableException eSU) {
   // unable to retrieve source
 }
static Set<Source> getSources()
          
 Set sources = SubjectFinder.getSources();
static Source internal_getGSA()
          TODO 20070803 what is the point of this method?
static void reset()
          Reset SubjectResolver.
static SubjectFinder.RestrictSourceForGroup restrictSourceForGroup(String stemName, String sourceId)
           
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

SubjectFinder

public SubjectFinder()
Method Detail

findByIdOrIdentifier

public static Subject findByIdOrIdentifier(String idOrIdentifier,
                                           boolean exceptionIfNull)
                                    throws SubjectNotFoundException,
                                           SubjectNotUniqueException
find by id or identifier

Parameters:
idOrIdentifier -
exceptionIfNull - if SubjectNotFoundException or null
Returns:
the subject
Throws:
SubjectNotFoundException
SubjectNotUniqueException

findByOptionalArgs

public static Subject findByOptionalArgs(String sourceId,
                                         String subjectId,
                                         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 Subject findByIdOrIdentifierAndSource(String idOrIdentifier,
                                                    String source,
                                                    boolean exceptionIfNull)
                                             throws SubjectNotFoundException,
                                                    SubjectNotUniqueException
find by id or identifier

Parameters:
idOrIdentifier -
source -
exceptionIfNull - if SubjectNotFoundException or null
Returns:
the subject
Throws:
SubjectNotFoundException
SubjectNotUniqueException

findById

@Deprecated
public static Subject findById(String id)
                        throws SubjectNotFoundException,
                               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:
SubjectNotFoundException
SubjectNotUniqueException

findById

public static Subject findById(String id,
                               boolean exceptionIfNull)
                        throws SubjectNotFoundException,
                               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:
SubjectNotFoundException
SubjectNotUniqueException

findByIdAndSource

public static Subject findByIdAndSource(String id,
                                        String source,
                                        boolean exceptionIfNull)
                                 throws SubjectNotFoundException,
                                        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:
SubjectNotFoundException
SubjectNotUniqueException

flushCache

public static void flushCache()
flush the cache (e.g. for testing)


findById

@Deprecated
public static Subject findById(String id,
                                          String type)
                        throws SubjectNotFoundException,
                               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:
SubjectNotFoundException
SubjectNotUniqueException

findById

@Deprecated
public static Subject findById(String id,
                                          String type,
                                          String source)
                        throws SourceUnavailableException,
                               SubjectNotFoundException,
                               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:
SourceUnavailableException
SubjectNotFoundException
SubjectNotUniqueException

findByIdentifier

@Deprecated
public static Subject findByIdentifier(String id)
                                throws SubjectNotFoundException,
                                       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:
SubjectNotFoundException
SubjectNotUniqueException

findByIdentifier

@Deprecated
public static Subject findByIdentifier(String id,
                                                  String type)
                                throws SubjectNotFoundException,
                                       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:
SubjectNotFoundException
SubjectNotUniqueException

findByIdentifier

@Deprecated
public static Subject findByIdentifier(String id,
                                                  String type,
                                                  String source)
                                throws SourceUnavailableException,
                                       SubjectNotFoundException,
                                       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:
SourceUnavailableException
SubjectNotFoundException
SubjectNotUniqueException

findAll

public static Set<Subject> findAll(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:
SubjectTooManyResults - if more results than configured

findAllInStem

public static Set<Subject> findAllInStem(String stemName,
                                         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:
SubjectTooManyResults - if more results than configured

findAll

public static Set<Subject> findAll(String query,
                                   String source)
                            throws 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:
SourceUnavailableException

findAll

public static Set<Subject> findAll(String query,
                                   Set<Source> sources)
                            throws 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:
SourceUnavailableException

findAllSubject

public static 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 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 Source getSource(String id)
                        throws IllegalArgumentException,
                               SourceUnavailableException
 try {
   Source sa = SubjectFinder.getSource(id);
 }
 catch (SourceUnavailableException eSU) {
   // unable to retrieve source
 }
 

Parameters:
id -
Returns:
Source identified by id.
Throws:
IllegalArgumentException - if id is null.
SourceUnavailableException - if unable to retrieve source.

getSources

public static Set<Source> getSources()
 Set sources = SubjectFinder.getSources();
 

Returns:
Set of all Source adapters.

internal_getGSA

public static Source internal_getGSA()
TODO 20070803 what is the point of this method?

Returns:
source
Since:
1.2.0

reset

public static void reset()
Reset SubjectResolver.

Since:
1.2.1

findById

@Deprecated
public static Subject findById(String id,
                                          String type,
                                          boolean exceptionIfNull)
                        throws SubjectNotFoundException,
                               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:
SubjectNotFoundException
SubjectNotUniqueException

findById

@Deprecated
public static Subject findById(String id,
                                          String type,
                                          String source,
                                          boolean exceptionIfNull)
                        throws SourceUnavailableException,
                               SubjectNotFoundException,
                               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:
SourceUnavailableException
SubjectNotFoundException
SubjectNotUniqueException

findByIdentifier

public static Subject findByIdentifier(String id,
                                       boolean exceptionIfNotFound)
                                throws SubjectNotFoundException,
                                       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:
SubjectNotFoundException
SubjectNotUniqueException

findByIdentifier

@Deprecated
public static Subject findByIdentifier(String id,
                                                  String type,
                                                  boolean exceptionIfNull)
                                throws SubjectNotFoundException,
                                       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:
SubjectNotFoundException
SubjectNotUniqueException

findByIdentifier

@Deprecated
public static Subject findByIdentifier(String id,
                                                  String type,
                                                  String source,
                                                  boolean exceptionIfNull)
                                throws SourceUnavailableException,
                                       SubjectNotFoundException,
                                       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:
SourceUnavailableException
SubjectNotFoundException
SubjectNotUniqueException

findBySubjectsInGroup

public static Set<Subject> findBySubjectsInGroup(GrouperSession grouperSession,
                                                 Set<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 Subject findByIdentifierAndSource(String identifier,
                                                String source,
                                                boolean exceptionIfNull)
                                         throws SourceUnavailableException,
                                                SubjectNotFoundException,
                                                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:
SourceUnavailableException
SubjectNotFoundException
SubjectNotUniqueException

findByPackedSubjectString

public static Subject findByPackedSubjectString(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(String stemName,
                                                                          String sourceId)
Parameters:
sourceId -
stemName -
Returns:
if restricted and to what extent