public class InstitutionMethods extends Object
All methods that return institutions also accept an optional
fetch parameter that may be used to request additional
information about the institutions returned. For more details about
the general rules that apply to the fetch parameter,
refer to the PersonMethods documentation.
For institutions the fetch parameter may be used to fetch
any institution attribute by specifying the schemeid of an
institution attribute scheme. Examples include "address",
"jpegPhoto", "universityPhone", "instPhone",
"landlinePhone", "mobilePhone", "faxNumber",
"email" and "labeledURI". The full list (which may be
extended over time) may be obtained using allAttributeSchemes().
In addition the following pseudo-attributes are supported:
"phone_numbers" - fetches all phone numbers. This is
equivalent to
"universityPhone,instPhone,landlinePhone,mobilePhone"."all_attrs" - fetches all attributes from all institution
attribute schemes. This does not include references."contact_rows" - fetches all institution contact rows. Any
chained fetches from contact rows are used to fetch attributes from any
people referred to by the contact rows.
The fetch parameter may also be used to fetch referenced
people, institutions or groups. This will only include references to
non-cancelled entities. The following references are supported:
"all_members" - fetches all the people who are members of the
institution."parent_insts" - fetches all the parent institutions. Note
that currently all institutions have only one parent, but this may change
in the future, and client applications should be prepared to handle
multiple parents."child_insts" - fetches all the child institutions."inst_groups" - fetches all the groups that belong to the
institution."members_groups" - fetches all the groups that form the
institution's membership list."managed_by_groups" - fetches all the groups that manage the
institution's data (commonly called "Editor" groups).
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 institution. For more information about what can be fetched from
referenced people and groups, refer to the documentation for
PersonMethods and GroupMethods.
| Constructor and Description |
|---|
InstitutionMethods(ClientConnection conn)
Create a new InstitutionMethods object.
|
| Modifier and Type | Method and Description |
|---|---|
IbisAttribute |
addAttribute(String instid,
IbisAttribute attr,
int position,
boolean allowDuplicates,
String commitComment)
Add an attribute to an institution.
|
List<IbisAttributeScheme> |
allAttributeSchemes()
Return a list of all the institution attribute schemes available.
|
List<IbisInstitution> |
allInsts(boolean includeCancelled,
String fetch)
Return a list of all institutions.
|
IbisGroup |
createGroup(String instid,
String name,
String title,
String description,
String managedBy,
String commitComment)
Create a group owned by an institution.
|
boolean |
deleteAttribute(String instid,
Long attrid,
String commitComment)
Delete an attribute of an institution.
|
IbisAttribute |
getAttribute(String instid,
Long attrid)
Get a specific attribute of an institution.
|
List<IbisAttribute> |
getAttributes(String instid,
String attrs)
Get one or more (possibly multi-valued) attributes of an institution.
|
List<IbisPerson> |
getCancelledMembers(String instid,
String fetch)
Get all the cancelled members of the specified institution.
|
List<IbisContactRow> |
getContactRows(String instid,
String fetch)
Get all the contact rows of the specified institution.
|
IbisInstitution |
getInst(String instid,
String fetch)
Get the institution with the specified ID.
|
List<IbisPerson> |
getMembers(String instid,
String fetch)
Get all the members of the specified institution.
|
List<IbisInstitution> |
listInsts(String instids,
String fetch)
Get the institutions with the specified IDs.
|
List<IbisInstitution> |
modifiedInsts(long minTxId,
long maxTxId,
String instids,
boolean includeCancelled,
boolean contactRowChanges,
boolean membershipChanges,
String fetch)
Find all institutions modified between the specified pair of
transactions.
|
List<IbisInstitution> |
search(String query,
boolean approxMatches,
boolean includeCancelled,
String attributes,
int offset,
int limit,
String orderBy,
String fetch)
Search for institutions using a free text query string.
|
int |
searchCount(String query,
boolean approxMatches,
boolean includeCancelled,
String attributes)
Count the number of institutions that would be returned by a search
using a free text query string.
|
IbisAttribute |
updateAttribute(String instid,
Long attrid,
IbisAttribute attr,
String commitComment)
Update an attribute of an institution.
|
public InstitutionMethods(ClientConnection conn)
conn - The ClientConnection object to use to invoke methods
on the server.public List<IbisAttributeScheme> allAttributeSchemes() throws IbisException, IOException, JAXBException
schemeid values of these schemes may be used in the
fetch parameter of other methods that return institutions.
[ HTTP: GET /api/v1/inst/all-attr-schemes ]
IbisExceptionIOExceptionJAXBExceptionpublic List<IbisInstitution> allInsts(boolean includeCancelled, String fetch) throws IbisException, IOException, JAXBException
By default, only a few basic details about each institution are
returned, but the optional fetch parameter may be used
to fetch additional attributes or references.
[ HTTP: GET /api/v1/inst/all-insts ]
includeCancelled - [optional] Whether or not to include cancelled
institutions. By default, only live institutions are returned.fetch - [optional] A comma-separated list of any additional
attributes or references to fetch.IbisExceptionIOExceptionJAXBExceptionpublic List<IbisInstitution> listInsts(String instids, String fetch) throws IbisException, IOException, JAXBException
By default, only a few basic details about each institution are
returned, but the optional fetch parameter may be used
to fetch additional attributes or references.
The results are sorted by ID.
NOTE: The URL path length is limited to around 8000 characters, and an instid is up to 8 characters long. Allowing for comma separators and URL encoding, this limits the number of institutions that this method may fetch to around 700.
NOTE: The institutions returned may include cancelled institutions. It is the caller's responsibility to check their cancelled flags.
[ HTTP: GET /api/v1/inst/list?instids=... ]
instids - [required] A comma-separated list of instids.fetch - [optional] A comma-separated list of any additional
attributes or references to fetch.IbisExceptionIOExceptionJAXBExceptionpublic List<IbisInstitution> modifiedInsts(long minTxId, long maxTxId, String instids, boolean includeCancelled, boolean contactRowChanges, boolean membershipChanges, String fetch) throws IbisException, IOException, JAXBException
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) institutions were affected.
By default, only a few basic details about each institution 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 institution. It is not possible to query for old data, or more detailed information about the specific changes made.
[ HTTP: GET /api/v1/inst/modified-insts?minTxId=...&maxTxId=... ]
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.instids - [optional] Only include institutions with instids in
this list. By default, all modified institutions will be included.includeCancelled - [optional] Include cancelled institutions. By
default, cancelled institutions are excluded.contactRowChanges - [optional] Include institutions whose contact
rows have changed. By default, changes to institution contact rows are
not taken into consideration.membershipChanges - [optional] Include institutions whose members
have changed. By default, changes to institutional memberships are not
taken into consideration.fetch - [optional] A comma-separated list of any additional
attributes or references to fetch.IbisExceptionIOExceptionJAXBExceptionpublic List<IbisInstitution> search(String query, boolean approxMatches, boolean includeCancelled, String attributes, int offset, int limit, String orderBy, String fetch) throws IbisException, IOException, JAXBException
By default, only a few basic details about each institution 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 "inst:", it
is treated as an LQL query, allowing
more advanced searches. An LQL query will ignore the
approxMatches and attributes parameters, 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/inst/search?query=... ]
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 institutions
to be included. Defaults to false.attributes - [optional] A comma-separated list of attributes to
consider when searching. If this is null (the default) then
all attribute schemes marked as searchable will be included. This is
ignored for LQL queries.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 either "instid" or "name" (the default for
non-LQL queries). This is ignored for LQL queries, which always return
results in instid order.fetch - [optional] A comma-separated list of any additional
attributes or references to fetch.IbisExceptionIOExceptionJAXBExceptionpublic int searchCount(String query, boolean approxMatches, boolean includeCancelled, String attributes) throws IbisException, IOException, JAXBException
NOTE: If the query string starts with the prefix "inst:", it
is treated as an LQL query, allowing
more advanced searches. An LQL query will ignore the
approxMatches and attributes parameters, but
it will respect the value of includeCancelled.
[ HTTP: GET /api/v1/inst/search-count?query=... ]
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 institutions
to be included. Defaults to false.attributes - [optional] A comma-separated list of attributes to
consider when searching. If this is null (the default) then
all attribute schemes marked as searchable will be included. This is
ignored for LQL queries.IbisExceptionIOExceptionJAXBExceptionpublic IbisInstitution getInst(String instid, String fetch) throws IbisException, IOException, JAXBException
By default, only a few basic details about the institution are
returned, but the optional fetch parameter may be used
to fetch additional attributes or references of the institution.
NOTE: The institution returned may be a cancelled institution. It is the caller's responsibility to check its cancelled flag.
[ HTTP: GET /api/v1/inst/{instid} ]
instid - [required] The ID of the institution to fetch.fetch - [optional] A comma-separated list of any additional
attributes or references to fetch.null if it was not found.IbisExceptionIOExceptionJAXBExceptionpublic IbisAttribute addAttribute(String instid, IbisAttribute attr, int position, boolean allowDuplicates, String commitComment) throws IbisException, IOException, JAXBException
When adding an attribute, the new attribute's scheme must be set. In addition, either its value or its binaryData field should be set. All the remaining fields of the attribute are optional.
[ HTTP: POST /api/v1/inst/{instid}/add-attribute ]
instid - [required] The ID of the institution.attr - [required] The new attribute to add.position - [optional] The position of the new attribute in the
list of attributes of the same attribute scheme (1, 2, 3,...). A value
of 0 (the default) will cause the new attribute to be added to the end
of the list of existing attributes for the scheme.allowDuplicates - [optional] If true, the new attribute
will always be added, even if another identical attribute already
exists. If false (the default), the new attribute will only be
added if it doesn't already exist.commitComment - [recommended] A short textual description of
the change made (will be visible on the history tab in the web
application).IbisExceptionIOExceptionJAXBExceptionpublic List<IbisPerson> getCancelledMembers(String instid, String fetch) throws IbisException, IOException, JAXBException
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 institution. 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 institutional memberships just before they were cancelled, and so is out-of-date data that should be used with caution.
[ HTTP: GET /api/v1/inst/{instid}/cancelled-members ]
instid - [required] The ID of the institution.fetch - [optional] A comma-separated list of any additional
attributes or references to fetch for each person.IbisExceptionIOExceptionJAXBExceptionpublic List<IbisContactRow> getContactRows(String instid, String fetch) throws IbisException, IOException, JAXBException
Any addresses, email addresses, phone numbers and web pages associated with the contact rows are automatically returned, as well as any people referred to by the contact rows.
If any of the contact rows refer to people, then only a few basic
details about each person 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/inst/{instid}/contact-rows ]
instid - [required] The ID of the institution.fetch - [optional] A comma-separated list of any additional
attributes or references to fetch for any people referred to by any
of the contact rows.IbisExceptionIOExceptionJAXBExceptionpublic IbisGroup createGroup(String instid, String name, String title, String description, String managedBy, String commitComment) throws IbisException, IOException, JAXBException
A new group will be created with the institution being its only owner.
Only limited attributes (short hyphenated name, title and description) of the new group can be specified when creating a group. The GroupMethod's update methods be used to modify other attributes. The new group will have membership visibility of 'university' and be managed by the same groups as its owning institution.
[ HTTP: POST /api/v1/inst/{instid}/create-group ]
instid - [required] The ID of the institution.name - [required] A short hyphenated name for the new group. Must be in lower case and
begin with the instid followed by a hyphen.title - [required] A title for the new group.description - [required] A more detailed description of the new group.managedBy - [optional] The sole group that will manage group data for the new group.
If not provided, the new group will be managed by the same groups as its owning institution.commitComment - [recommended] A short textual description of
the change made (will be visible on the history tab in the web
application).IbisExceptionIOExceptionJAXBExceptionpublic List<IbisAttribute> getAttributes(String instid, String attrs) throws IbisException, IOException, JAXBException
[ HTTP: GET /api/v1/inst/{instid}/get-attributes?attrs=... ]
instid - [required] The ID of the institution.attrs - [required] The attribute scheme(s) to fetch. This may
include any number of the attributes or pseudo-attributes, but it
may not include references or attribute chains (see the documentation
for the fetch parameter in this class).IbisExceptionIOExceptionJAXBExceptionpublic List<IbisPerson> getMembers(String instid, String fetch) throws IbisException, IOException, JAXBException
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/inst/{instid}/members ]
instid - [required] The ID of the institution.fetch - [optional] A comma-separated list of any additional
attributes or references to fetch for each person.IbisExceptionIOExceptionJAXBExceptionpublic boolean deleteAttribute(String instid, Long attrid, String commitComment) throws IbisException, IOException, JAXBException
Note that in this method, the commitComment is passed
as a query parameter, rather than as a form parameter, for greater
client compatibility.
[ HTTP: DELETE /api/v1/inst/{instid}/{attrid} ]
instid - [required] The ID of the institution.attrid - [required] The ID of the attribute to delete.commitComment - [recommended] A short textual description of
the change made (will be visible on the history tab in the web
application).true if the attribute was deleted by this method, or
false if it did not exist.IbisExceptionIOExceptionJAXBExceptionpublic IbisAttribute getAttribute(String instid, Long attrid) throws IbisException, IOException, JAXBException
[ HTTP: GET /api/v1/inst/{instid}/{attrid} ]
instid - [required] The ID of the institution.attrid - [required] The ID of the attribute to fetch.IbisExceptionIOExceptionJAXBExceptionpublic IbisAttribute updateAttribute(String instid, Long attrid, IbisAttribute attr, String commitComment) throws IbisException, IOException, JAXBException
The attribute's value, binaryData, comment and effective date fields will all be updated using the data supplied. All other fields will be left unchanged.
To avoid inadvertently changing fields of the attribute, it is
recommended that getAttribute() be used to
retrieve the current value of the attribute, before calling this
method with the required changes.
[ HTTP: PUT /api/v1/inst/{instid}/{attrid} ]
instid - [required] The ID of the institution.attrid - [required] The ID of the attribute to update.attr - [required] The new attribute values to apply.commitComment - [recommended] A short textual description of
the change made (will be visible on the history tab in the web
application).IbisExceptionIOExceptionJAXBException