uk.ac.cam.ucs.ibis.methods

Class GroupMethods

java.lang.Object

uk.ac.cam.ucs.ibis.methods.GroupMethods

public class GroupMethods
extends Object

Methods for querying and manipulating groups.

The fetch parameter for groups

All methods that return groups also accept an optional fetch parameter that may be used to request additional information about the groups returned. For more details about the general rules that apply to the fetch parameter, refer to the PersonMethods documentation.

For groups the fetch parameter may be used to fetch references to people, institutions or other groups. In each case, only non-cancelled people, institutions and groups will be included when fetching references. The following references are supported:

• "all_members" - fetches all the people who are members of the group, including members of groups included by the group, and groups included by those groups, and so on.
• "direct_members" - fetches all the people who are direct members of the group, not taking into account any included groups.
• "members_of_inst" - if the group is a membership group for an institution, this fetches that institution.
• "owning_insts" - fetches all the institutions to which the group belongs.
• "manages_insts" - fetches all the institutions that the group manages. Typically this only applies to "Editor" groups.
• "manages_groups" - fetches all the groups that this group manages. Note that some groups are self-managed, so this may be a self-reference.
• "managed_by_groups" - fetches all the groups that manage this group.
• "reads_groups" - fetches all the groups that this group has privileged access to. This means that members of this group can see the members of the referenced groups regardless of the membership visibility settings.
• "read_by_groups" - fetches all the groups that have privileged access to this group.
• "includes_groups" - fetches all the groups included by this group.
• "included_by_groups" - fetches all the groups that include this group.

As with person fetch parameters, the references may be used in a chain by using the "dot" notation to fetch additional information about referenced people, institutions or groups. For example "all_members.email" will fetch the email addresses of all members of the group. For more information about what can be fetched from referenced people and institutions, refer to the documentation for PersonMethods and InstitutionMethods.

Constructor Summary

Constructors

Constructor and Description
GroupMethods(ClientConnection conn) Create a new GroupMethods object.

Method Summary

Modifier and Type	Method and Description
List<IbisGroup>	allGroups(boolean includeCancelled, String fetch) Return a list of all groups.
List<IbisPerson>	getCancelledMembers(String groupid, String fetch) Get all the cancelled members of the specified group, including cancelled members of groups included by the group, and groups included by those groups, and so on.
List<IbisPerson>	getDirectMembers(String groupid, String fetch) Get the direct members of the specified group, not including members included via groups included by the group.
IbisGroup	getGroup(String groupid, String fetch) Get the group with the specified ID or name.
List<IbisPerson>	getMembers(String groupid, String fetch) Get all the members of the specified group, including members of groups included by the group, and groups included by those groups, and so on.
String	getToken(String groupid, String aud) Get a signed JSON Web Token (JWT) with the group as subject and specified audience, only if authorized user/group has permission to edit the group.
List<IbisGroup>	listGroups(String groupids, String fetch) Get the groups with the specified IDs or names.
List<IbisGroup>	modifiedGroups(long minTxId, long maxTxId, String groupids, boolean includeCancelled, boolean membershipChanges, String fetch) Find all groups modified between the specified pair of transactions.
List<IbisGroup>	search(String query, boolean approxMatches, boolean includeCancelled, int offset, int limit, String orderBy, String fetch) Search for groups using a free text query string.
int	searchCount(String query, boolean approxMatches, boolean includeCancelled) Count the number of groups that would be returned by a search using a free text query string.
List<IbisPerson>	updateDirectMembers(String groupid, String addIds, String removeIds, String commitComment) Update the list of people who are direct members of the group.

Methods inherited from class java.lang.Object

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

Constructor Detail

GroupMethods

public GroupMethods(ClientConnection conn)

Create a new GroupMethods object.

Parameters:

conn - The ClientConnection object to use to invoke methods on the server.

Method Detail

allGroups

public List<IbisGroup> allGroups(boolean includeCancelled,
                                 String  fetch)
    throws IbisException,
           IOException,
           JAXBException

Return a list of all groups.

By default, only a few basic details about each group are returned, but the optional fetch parameter may be used to fetch additional attributes or references.

[ HTTP: GET /api/v1/group/all-groups ]

Parameters:

includeCancelled - [optional] Whether or not to include cancelled groups. By default, only live groups are returned.

fetch - [optional] A comma-separated list of any additional attributes or references to fetch.

Returns:

The requested groups (in groupid order).

Throws:

IbisException

IOException

JAXBException

listGroups

public List<IbisGroup> listGroups(String groupids,
                                  String fetch)
    throws IbisException,
           IOException,
           JAXBException

Get the groups with the specified IDs or names.

By default, only a few basic details about each group are returned, but the optional fetch parameter may be used to fetch additional attributes or references.

The results are sorted by groupid.

NOTE: The URL path length is limited to around 8000 characters, which limits the number of groups that this method can fetch. Group IDs are currently 6 characters long, and must be comma separated and URL encoded, which limits this method to around 800 groups by ID, but probably fewer by name, depending on the group name lengths.

NOTE: The groups returned may include cancelled groups. It is the caller's responsibility to check their cancelled flags.

[ HTTP: GET /api/v1/group/list?groupids=... ]

Parameters:

groupids - [required] A comma-separated list of group IDs or group names (may be a mix of both).

fetch - [optional] A comma-separated list of any additional attributes or references to fetch.

Returns:

The requested groups (in groupid order).

Throws:

IbisException

IOException

JAXBException

modifiedGroups

public List<IbisGroup> modifiedGroups(long    minTxId,
                                      long    maxTxId,
                                      String  groupids,
                                      boolean includeCancelled,
                                      boolean membershipChanges,
                                      String  fetch)
    throws IbisException,
           IOException,
           JAXBException

Find all groups modified between the specified pair of transactions.

The transaction IDs specified should be the IDs from two different requests for the last (most recent) transaction ID, made at different times, that returned different values, indicating that some Lookup data was modified in the period between the two requests. This method then determines which (if any) groups were affected.

By default, only a few basic details about each group are returned, but the optional fetch parameter may be used to fetch additional attributes or references.

NOTE: All data returned reflects the latest available data about each group. It is not possible to query for old data, or more detailed information about the specific changes made.

[ HTTP: GET /api/v1/group/modified-groups?minTxId=...&maxTxId=... ]

Parameters:

minTxId - [required] Include modifications made in transactions after (but not including) this one.

maxTxId - [required] Include modifications made in transactions up to and including this one.

groupids - [optional] Only include groups with IDs or names in this list. By default, all modified groups will be included.

includeCancelled - [optional] Include cancelled groups. By default, cancelled groups are excluded.

membershipChanges - [optional] Include groups whose members have changed. By default, changes to group memberships are not taken into consideration.

fetch - [optional] A comma-separated list of any additional attributes or references to fetch.

Returns:

The modified groups (in groupid order).

Throws:

IbisException

IOException

JAXBException

search

public List<IbisGroup> search(String  query,
                              boolean approxMatches,
                              boolean includeCancelled,
                              int     offset,
                              int     limit,
                              String  orderBy,
                              String  fetch)
    throws IbisException,
           IOException,
           JAXBException

Search for groups using a free text query string. This is the same search function that is used in the Lookup web application.

By default, only a few basic details about each group are returned, but the optional fetch parameter may be used to fetch additional attributes or references.

NOTE: If the query string starts with the prefix "group:", it is treated as an LQL query, allowing more advanced searches. An LQL query will ignore the approxMatches parameter, but it will respect the value of includeCancelled. In addition, an LQL query will ignore the orderBy parameter, since LQL queries always return results in ID order.

[ HTTP: GET /api/v1/group/search?query=... ]

Parameters:

query - [required] The search string.

approxMatches - [optional] Flag to enable more approximate matching in the search, causing more results to be returned. Defaults to false. This is ignored for LQL queries.

includeCancelled - [optional] Flag to allow cancelled groups to be included. Defaults to false.

offset - [optional] The number of results to skip at the start of the search. Defaults to 0.

limit - [optional] The maximum number of results to return. Defaults to 100.

orderBy - [optional] The order in which to list the results. This may be "groupid", "name" (the default for non-LQL queries) or "title". This is ignored for LQL queries, which always return results in groupid order.

fetch - [optional] A comma-separated list of any additional attributes or references to fetch.

Returns:

The matching groups.

Throws:

IbisException

IOException

JAXBException

searchCount

public int searchCount(String  query,
                       boolean approxMatches,
                       boolean includeCancelled)
    throws IbisException,
           IOException,
           JAXBException

Count the number of groups that would be returned by a search using a free text query string.

NOTE: If the query string starts with the prefix "group:", it is treated as an LQL query, allowing more advanced searches. An LQL query will ignore the approxMatches parameter, but it will respect the value of includeCancelled.

[ HTTP: GET /api/v1/group/search-count?query=... ]

Parameters:

query - [required] The search string.

approxMatches - [optional] Flag to enable more approximate matching in the search, causing more results to be returned. Defaults to false. This is ignored for LQL queries.

includeCancelled - [optional] Flag to allow cancelled groups to be included. Defaults to false.

Returns:

The number of matching groups.

Throws:

IbisException

IOException

JAXBException

getGroup

public IbisGroup getGroup(String groupid,
                          String fetch)
    throws IbisException,
           IOException,
           JAXBException

Get the group with the specified ID or name.

By default, only a few basic details about the group are returned, but the optional fetch parameter may be used to fetch additional attributes or references of the group.

NOTE: The group returned may be a cancelled group. It is the caller's responsibility to check its cancelled flag.

[ HTTP: GET /api/v1/group/{groupid} ]

Parameters:

groupid - [required] The ID or name of the group to fetch. This may be either the numeric ID or the short hyphenated group name (for example "100656" or "cs-editors").

fetch - [optional] A comma-separated list of any additional attributes or references to fetch.

Returns:

The requested group or null if it was not found.

Throws:

IbisException

IOException

JAXBException

getCancelledMembers

public List<IbisPerson> getCancelledMembers(String groupid,
                                            String fetch)
    throws IbisException,
           IOException,
           JAXBException

Get all the cancelled members of the specified group, including cancelled members of groups included by the group, and groups included by those groups, and so on.

By default, only a few basic details about each member are returned, but the optional fetch parameter may be used to fetch additional attributes or references of each person.

NOTE: This method returns only cancelled people. It does not include people who were removed from the group. Cancelled people are no longer considered to be current staff, students or accredited visitors, and are no longer regarded as belonging to any groups or institutions. The list returned here reflects their group memberships just before they were cancelled, and so is out-of-date data that should be used with caution.

[ HTTP: GET /api/v1/group/{groupid}/cancelled-members ]

Parameters:

groupid - [required] The ID or name of the group.

fetch - [optional] A comma-separated list of any additional attributes or references to fetch for each person.

Returns:

The group's cancelled members (in identifier order).

Throws:

IbisException

IOException

JAXBException

getDirectMembers

public List<IbisPerson> getDirectMembers(String groupid,
                                         String fetch)
    throws IbisException,
           IOException,
           JAXBException

Get the direct members of the specified group, not including members included via groups included by the group.

By default, only a few basic details about each member are returned, but the optional fetch parameter may be used to fetch additional attributes or references of each person.

NOTE: This method will not include cancelled people.

[ HTTP: GET /api/v1/group/{groupid}/direct-members ]

Parameters:

groupid - [required] The ID or name of the group.

fetch - [optional] A comma-separated list of any additional attributes or references to fetch for each person.

Returns:

The group's direct members (in identifier order).

Throws:

IbisException

IOException

JAXBException

updateDirectMembers

public List<IbisPerson> updateDirectMembers(String groupid,
                                            String addIds,
                                            String removeIds,
                                            String commitComment)
    throws IbisException,
           IOException,
           JAXBException

Update the list of people who are direct members of the group. This will not affect people who are included in the group due to the inclusion of other groups.

Any non-cancelled people in the list of identifiers specified by addIds will be added to the group. This list should be a comma-separated list of identifiers, each of which may be either a CRSid or an identifier from another identifier scheme, prefixed with that scheme's name and a slash. For example "mug99" or "usn/123456789".

Any people in the list of identifiers specified by removeIds will be removed from the group, except if they are also in the list addIds. The special identifier "all-members" may be used to remove all existing group members, replacing them with the list specified by newIds.

Examples:

 updateDirectMembers("test-group",
                     "mug99,crsid/yyy99,usn/123456789",
                     "xxx99",
                     "Remove xxx99 and add mug99, yyy99 and usn/123456789 to test-group");
 

 updateDirectMembers("test-group",
                     "xxx99,yyy99",
                     "all-members",
                     "Set the membership of test-group to include only xxx99 and yyy99");
 

[ HTTP: PUT /api/v1/group/{groupid}/direct-members ]

Parameters:

groupid - [required] The ID or name of the group.

addIds - [optional] The identifiers of people to add to the group.

removeIds - [optional] The identifiers of people to remove from the group.

commitComment - [recommended] A short textual description of the change made (will be visible on the history tab of the group and all the affected people in the web application).

Returns:

The updated list of direct members of the group (in identifier order).

Throws:

IbisException

IOException

JAXBException

getMembers

public List<IbisPerson> getMembers(String groupid,
                                   String fetch)
    throws IbisException,
           IOException,
           JAXBException

Get all the members of the specified group, including members of groups included by the group, and groups included by those groups, and so on.

By default, only a few basic details about each member are returned, but the optional fetch parameter may be used to fetch additional attributes or references of each person.

NOTE: This method will not include cancelled people.

[ HTTP: GET /api/v1/group/{groupid}/members ]

Parameters:

groupid - [required] The ID or name of the group.

fetch - [optional] A comma-separated list of any additional attributes or references to fetch for each person.

Returns:

The group's members (in identifier order).

Throws:

IbisException

IOException

JAXBException

getToken

public String getToken(String groupid,
                       String aud)
    throws IbisException,
           IOException,
           JAXBException

Get a signed JSON Web Token (JWT) with the group as subject and specified audience, only if authorized user/group has permission to edit the group.

[ HTTP: GET /api/v1/group/{groupid}/token?aud=... ]

Parameters:

groupid - [required] The ID of the group.

aud - [required] Audience for the signed JWT.

Returns:

The serialized JWT

Throws:

IbisException

IOException

JAXBException