us.openinternet.luge.valueobject
Class SearchVO

java.lang.Object
  |
  +--us.openinternet.luge.valueobject.SearchVO
All Implemented Interfaces:
java.io.Serializable

public class SearchVO
extends java.lang.Object
implements java.io.Serializable

This object is used both to describe a search to perform and as a container for results. It is used only to search for People and Groups via the SimpleFacade's searchUsers or searchGroups methods.

For searching, you can use the object to: (1) Set include and exclude parameters; (2) Specify that people returned from a search must be members of a certain group; (3) specify a timelimit in seconds; (4) specify what attributes you would like returned; (5) set the logical operators AND or OR (and in the case of groups, NOT); (6) if you are authorized to access PD information, you can set a flag that lets you specify that you only want active or inactive persons returned and (7) set a search filter directly if you feel that the automatic inlcude/exclude parameters provided are not sufficient for expressing a certain search.

For extracting search results, you can use the object to: (1) get an Iterator of PersonVO or GroupVO objects returned sorted by name, or another specified attribute (2) get a list the names of the entries that are returned (the keys); (3) retreive a specific entry by specifying its name and (4) get a list of the distinct values for a given attribute (for all the entries contained in the SearchVO object).

Here is sample code for how a search might happen:

Note: if you are only looking to get a value or values for a single attribute, there is an easier way to do it: use the SimpleFacade's getUserAttributeSingleValue which returns a String, or getUserAttributeMultiValue which returns an ArrayList of Strings.

See Also:
Serialized Form

Constructor Summary
SearchVO()
           
 
Method Summary
 boolean contains(java.lang.String entryName)
          Same method as has_entry.
 void excludeAttribute(java.lang.String attr, java.lang.String value)
          Exclude a single attribute and value from the search, wildcards ok.
 void excludeAttributes(java.util.Hashtable ht)
          Allows you to add multiple excludes by using a Hashtable.
 void excludeLogicalOperator(java.lang.String newOperator)
          Sets the logical operator for the include parameters If you don't call this method, the default search is AND.
 java.util.ArrayList getDistinctValues(java.lang.String attrName)
          Use this method to return the sorted distinct values of a given attribute for all entries contained in the SearchVO object.
 java.util.ArrayList getDistinctValues(java.lang.String attrName, boolean integerSortFlag)
          Same as other method except boolean flag enables you to sort the values as integers instead of by string.
 java.util.Iterator getEntries()
          Returns an Iterator of ValueObjects (either group or person) sorted by entry name.
 java.util.Iterator getEntriesIntegerSorted(java.lang.String attrName)
          Returns an Iterator of ValueObjects sorted by the integer values for the specified attribute
 java.util.Iterator getEntriesReverseSorted(java.lang.String attrName)
          Retuns an Iterator reverse sorted based on the specified attribute
 java.util.Iterator getEntriesSorted(java.lang.String attrName)
          Returns an Iterator of ValueObjects sorted by the specified attribute
 java.util.Iterator getEntriesSorted(java.lang.String attrName, boolean integerSortFlag)
          Returns an Iterator of ValueObjects sorted by entry name.
 java.util.ArrayList getEntryNames()
          Returns an ArrayList of entry names (Strings), which can be used with the getUserEntry or getGroupEntry respectively to get specific data.
 java.util.ArrayList getExcludes()
          A list of the paramters to exclude
 java.lang.String getFilter()
          Returns the current ldap search filter as a string
 java.lang.String getFlag()
          Used by the facade to determine which ou to search
 GroupVO getGroupEntry(java.lang.String entryName)
          Returns VO for the group specified by the key or null.
 java.util.ArrayList getGroupFilter()
           
 java.lang.String getGroupLogicalOperator()
           
 java.util.ArrayList getIncludes()
          A list of the paramters to include
 java.lang.String[] getReturnAttributes()
          A list of the attributes that you have specified you want returned
 boolean getStatusFlag()
          Returns the status flag which is set to true if the search should return only PD active users, false to return inactive PD users.
 int getTimeLimit()
          The time limit (in seconds) that you have specified
 PersonVO getUserEntry(java.lang.String entryName)
          Returns VO for the person specified by the key or null.
 void groupLogicalOperator(java.lang.String newOperator)
          Sets the logical operator for the group membership check--only applicable to searching users.
 boolean has_entry(java.lang.String entryName)
          Check to see if SearchVO has a certain entry, index by cn (or possibly uid for people)
 void includeAttribute(java.lang.String attr, java.lang.String value)
          Include a single attribute and value in the search, wildcards ok.
 void includeAttributes(java.util.Hashtable ht)
          Allows you to add multiple includes by using a Hashtable.
 void includeLogicalOperator(java.lang.String newOperator)
          Sets the logical operator for the include parameters.
 void loadResults(java.util.Hashtable newEntries)
          Used by the Facade to load the SearchVO object with attributes and values
 void removeEntries(java.util.ArrayList entryNames)
          Use this method to remove ValueObject entries from the SearchVO.
 void returnAttributes(java.lang.String[] attrs)
          A String[] of the ldap attributes you want returned.
 void setFilter(java.lang.String newFilter)
          This method allows you to set the filter manually.
 void setGroupFilter(java.util.ArrayList groups)
          Has the effect of filtering the users returned from a search (determined by the filter) based on their membership to one or all (depending on the groupLogicalOperator) of the groups specified in this groups ArrayList.
 void setGroupFilter(java.util.ArrayList groups, java.lang.String logicalOperator)
          Convenience method: set the groups and logicalOperator in one method
 void setGroupFilter(java.lang.String groupCN)
          Convenience method if you only have one group.
 void setGroupFlag()
          Used by the facade
 void setStausFlag(boolean newStatus)
          If the status flag is set to true, only active users will be returned; false and only inactive users will be returned.
 void setUserFlag()
          Used by the facade
 int size()
          Returns the number of matching entries
 void timeLimit(int newTimeLimit)
          The maximum time in seconds to wait for the ldap server to return results
 java.lang.String toString()
          Returns a string representation of the underlying TreeMap data structure
 void updateGroup(GroupVO gvo)
          Use this method to add or update Groups in the SearchVO one at a time.
 void updatePerson(PersonVO pvo)
          Use this method to add or update People in the SearchVO one at a time.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

SearchVO

public SearchVO()
Method Detail

includeAttribute

public void includeAttribute(java.lang.String attr,
                             java.lang.String value)
Include a single attribute and value in the search, wildcards ok. For example, mySeachVO.includeAttribute("cn", "foo*") If you need to search for a "*", "(", ")" or "\" character, it must be escaped (ie put an extra "\" before the character you want to escape.

Parameters:
attr - -- The actual ldap name of the attribute
value - -- Value you want to search for, wildcards ok.

includeAttributes

public void includeAttributes(java.util.Hashtable ht)
Allows you to add multiple includes by using a Hashtable. The keys should be Strings with valid ldap attributes; the values should be Strings with the corresponding values you want to search for. For example: search for all people with with username (cn) foo* at location (l) WoodCliff Lake:

If you need to search for a "*", "(", ")" or "\" character, it must be escaped (ie put an extra "\" before the character you want to escape.

Parameters:
ht - -- Hashtable with ldap attribute names as keys and corresponding values to search for.

excludeAttribute

public void excludeAttribute(java.lang.String attr,
                             java.lang.String value)
Exclude a single attribute and value from the search, wildcards ok. For example, mySeachVO.excludeAttribute("l", "Newark")

Parameters:
attr - -- The actual ldap name of the attribute
value - -- Value you want to search for, wildcards ok.

excludeAttributes

public void excludeAttributes(java.util.Hashtable ht)
Allows you to add multiple excludes by using a Hashtable. The keys should be Strings with valid ldap attribute names; the values should be Strings with the corresponding value (wildcards ok); For example:

Parameters:
ht - -- Hashtable with ldap attribute names as keys and corresponding values to exclude from the search.

setGroupFilter

public void setGroupFilter(java.util.ArrayList groups)
Has the effect of filtering the users returned from a search (determined by the filter) based on their membership to one or all (depending on the groupLogicalOperator) of the groups specified in this groups ArrayList.


setGroupFilter

public void setGroupFilter(java.util.ArrayList groups,
                           java.lang.String logicalOperator)
Convenience method: set the groups and logicalOperator in one method


setGroupFilter

public void setGroupFilter(java.lang.String groupCN)
Convenience method if you only have one group.


setStausFlag

public void setStausFlag(boolean newStatus)
If the status flag is set to true, only active users will be returned; false and only inactive users will be returned. Default value is true. Note, you must be authorized to access PD entries in order to use the AdminFaccade.getUsersByStatus method.


timeLimit

public void timeLimit(int newTimeLimit)
The maximum time in seconds to wait for the ldap server to return results


returnAttributes

public void returnAttributes(java.lang.String[] attrs)
A String[] of the ldap attributes you want returned. If you do not set this, all attribute will be returned.


includeLogicalOperator

public void includeLogicalOperator(java.lang.String newOperator)
Sets the logical operator for the include parameters. If you don't call this method, the default search is AND.

Parameters:
newOperator - Either "|", "&", "or", "and" : case insensitive.

excludeLogicalOperator

public void excludeLogicalOperator(java.lang.String newOperator)
Sets the logical operator for the include parameters If you don't call this method, the default search is AND.

Parameters:
newOperator - Either "|", "&", "or", "and" : case insensitive.

groupLogicalOperator

public void groupLogicalOperator(java.lang.String newOperator)
Sets the logical operator for the group membership check--only applicable to searching users. If you don't call this method, the default search is AND, which has the effect of requiring membership in all the groups specied in the setGroupFilter method.

Parameters:
newOperator - Either "|", "&", "!", "or", "and", "not" : case insensitive.

getStatusFlag

public boolean getStatusFlag()
Returns the status flag which is set to true if the search should return only PD active users, false to return inactive PD users. Default is true.


getTimeLimit

public int getTimeLimit()
The time limit (in seconds) that you have specified


getIncludes

public java.util.ArrayList getIncludes()
A list of the paramters to include


getExcludes

public java.util.ArrayList getExcludes()
A list of the paramters to exclude


getReturnAttributes

public java.lang.String[] getReturnAttributes()
A list of the attributes that you have specified you want returned


size

public int size()
Returns the number of matching entries


getGroupFilter

public java.util.ArrayList getGroupFilter()

getGroupLogicalOperator

public java.lang.String getGroupLogicalOperator()

has_entry

public boolean has_entry(java.lang.String entryName)
Check to see if SearchVO has a certain entry, index by cn (or possibly uid for people)


contains

public boolean contains(java.lang.String entryName)
Same method as has_entry. Provided for convenience


getEntryNames

public java.util.ArrayList getEntryNames()
Returns an ArrayList of entry names (Strings), which can be used with the getUserEntry or getGroupEntry respectively to get specific data.


getDistinctValues

public java.util.ArrayList getDistinctValues(java.lang.String attrName)
Use this method to return the sorted distinct values of a given attribute for all entries contained in the SearchVO object. Results returned sorted (either alphabetically (ignoring case), or by integer. Note, even if you sort by integer values, the ArrayList returns String objects.

Parameters:
attrName - The actual ldap attribute name of the distinct values you want returned.

getDistinctValues

public java.util.ArrayList getDistinctValues(java.lang.String attrName,
                                             boolean integerSortFlag)
Same as other method except boolean flag enables you to sort the values as integers instead of by string.

Parameters:
attrName - The actual ldap attribute name of the distinct values you want returned.
integerSortFlag - set boolean to true for integer sorting

getEntries

public java.util.Iterator getEntries()
Returns an Iterator of ValueObjects (either group or person) sorted by entry name.


getEntriesSorted

public java.util.Iterator getEntriesSorted(java.lang.String attrName)
Returns an Iterator of ValueObjects sorted by the specified attribute


getEntriesIntegerSorted

public java.util.Iterator getEntriesIntegerSorted(java.lang.String attrName)
Returns an Iterator of ValueObjects sorted by the integer values for the specified attribute


getEntriesReverseSorted

public java.util.Iterator getEntriesReverseSorted(java.lang.String attrName)
Retuns an Iterator reverse sorted based on the specified attribute


getEntriesSorted

public java.util.Iterator getEntriesSorted(java.lang.String attrName,
                                           boolean integerSortFlag)
Returns an Iterator of ValueObjects sorted by entry name.

Parameters:
attrName - - the name of the attribute to sort on

getUserEntry

public PersonVO getUserEntry(java.lang.String entryName)
Returns VO for the person specified by the key or null.

Parameters:
entryName - -- The key. For a list of keys use the getEntryNames method.
Returns:
PersonVO or empty PersonVO

getGroupEntry

public GroupVO getGroupEntry(java.lang.String entryName)
Returns VO for the group specified by the key or null.

Parameters:
entryName - -- The key: for a list of keys use the getEntryNames method.
Returns:
GroupVO or null

setFilter

public void setFilter(java.lang.String newFilter)
This method allows you to set the filter manually. You must understand the ldap filter syntax to use this method see RFC 2254 http://www.faqs.org/rfcs/rfc2254.html


getFilter

public java.lang.String getFilter()
Returns the current ldap search filter as a string


toString

public java.lang.String toString()
Returns a string representation of the underlying TreeMap data structure

Overrides:
toString in class java.lang.Object

loadResults

public void loadResults(java.util.Hashtable newEntries)
Used by the Facade to load the SearchVO object with attributes and values


updatePerson

public void updatePerson(PersonVO pvo)
Use this method to add or update People in the SearchVO one at a time. If a PersonVO by that name already exists, it will be overwritten.


updateGroup

public void updateGroup(GroupVO gvo)
Use this method to add or update Groups in the SearchVO one at a time. If a GroupVO by that name already exists, it will be overwritten.


removeEntries

public void removeEntries(java.util.ArrayList entryNames)
Use this method to remove ValueObject entries from the SearchVO. Post a list of the VO names (ie uids or Group names).

Parameters:
entryNames - An ArrayList of names of the VOs (Strings)

setUserFlag

public void setUserFlag()
Used by the facade


setGroupFlag

public void setGroupFlag()
Used by the facade


getFlag

public java.lang.String getFlag()
Used by the facade to determine which ou to search


Copyright 2003, Michael Schwartz All Rights Reserved.