com.yosokumo.core
Class Service

java.lang.Object
  com.yosokumo.core.Service

public class Service
extends java.lang.Object

Provides the basic operations available from the Yosokumo web service, e.g., obtainCatalog and createStudy. Whenever a basic operation fails, it throws a ServiceException. See ServiceException for a description of the possible exceptions.

Nested Class Summary

static class

Service.DIFType Specifies the Data Interchange Format (DIF) of bytes transmitted to and from the Yosokumo server.

Constructor Summary

Service()
Initializes a newly created Service object using defaults for the credentials, host name, port, and DIF.

Service(Credentials credentials)
Initializes a newly created Service object with attributes specified by the input parameters, using defaults for the host name, port, and DIF.

Service(Credentials credentials, java.lang.String hostName)
Initializes a newly created Service object with attributes specified by the input parameters, using defaults for the port and DIF.

Service(Credentials credentials, java.lang.String hostName, int port)
Initializes a newly created Service object with attributes specified by the input parameters, using a default for the DIF.

Service(Credentials credentials, java.lang.String hostName, int port, Service.DIFType dif)
Initializes a newly created Service object with attributes specified by the input parameters.

Method Summary

Role	createRole(Role role) Add a Role to a study's roster.
Study	createStudy() Create a default study and add it to the user's catalog of studies.
Study	createStudy(java.lang.String studyName) Create a named study and add it to the user's catalog of studies.
Study	createStudy(java.lang.String studyName, Study.Type studyType) Create a study with specified name and type and add it to the user's catalog of studies.
Study	createStudy(java.lang.String studyName, Study.Type studyType, Study.Status studyStatus, Study.Visibility studyVisibility) Create a study with specified name, type, status, and visibility, and add it to the user's catalog of studies.
void	deleteRole(java.lang.String userId, java.lang.String studyId) Delete a role.
void	deleteStudy(java.lang.String studyId) Delete a study from the server.
void	describePredictors(java.lang.String studyId, java.util.List<Predictor> predictorList) Describe a study's predictors.
int	getStatusCode() Return the status code from the last Service operation.
void	loadSubjects(java.lang.String studyId, java.util.List<Specimen> specimenList) Populate the rows of a study's table with subjects.
Catalog	obtainCatalog() Obtain the user's catalog of studies.
Role	obtainRole(java.lang.String userId, java.lang.String studyId) Obtain a role.
Roster	obtainRoster(java.lang.String studyId) Obtain the roster for a study.
Study	obtainStudy(java.lang.String studyId) Obtain a study from the server.
void	scoreProspects(java.lang.String studyId, java.util.List<Specimen> specimenList) Score prospects (compute predictands) using a study's model.
Message	updateRole(Role role) Update a role on the server.
Study	updateStudy(java.lang.String studyId, java.lang.String studyName) Update a study, changing the study name.
Study	updateStudy(java.lang.String studyId, Study.Status studyStatus) Update a study, changing the status.
Study	updateStudy(java.lang.String studyId, Study.Visibility studyVisibility) Update a study, changing the visibility.

Methods inherited from class java.lang.Object

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

Constructor Detail

Service

public Service()
        throws ServiceException

Initializes a newly created Service object using defaults for the credentials, host name, port, and DIF.

Throws:

ServiceException

Service

public Service(Credentials credentials)
        throws ServiceException

Initializes a newly created Service object with attributes specified by the input parameters, using defaults for the host name, port, and DIF.

Parameters:

credentials - user id and key for authentication.

Throws:

ServiceException

Service

public Service(Credentials credentials,
               java.lang.String hostName)
        throws ServiceException

Initializes a newly created Service object with attributes specified by the input parameters, using defaults for the port and DIF.

Parameters:

credentials - user id and key for authentication.

hostName - host name for the Yosokumo server.

Throws:

ServiceException

Service

public Service(Credentials credentials,
               java.lang.String hostName,
               int port)
        throws ServiceException

Initializes a newly created Service object with attributes specified by the input parameters, using a default for the DIF.

Parameters:

credentials - user id and key for authentication.

hostName - host name for the Yosokumo server.

port - port to use for HTTP communication.

Throws:

ServiceException

Service

public Service(Credentials credentials,
               java.lang.String hostName,
               int port,
               Service.DIFType dif)
        throws ServiceException

Initializes a newly created Service object with attributes specified by the input parameters.

Parameters:

credentials - user id and key for authentication.

hostName - host name for the Yosokumo server.

port - port to use for HTTP communication.

dif - specifies the DIF to use to talk to the server.

Throws:

ServiceException - if the DIF is not implemented

Method Detail

getStatusCode

public int getStatusCode()

Return the status code from the last Service operation.

Returns:

the status code.

obtainCatalog

public Catalog obtainCatalog()
                      throws ServiceException

Obtain the user's catalog of studies.

Returns:

a reference to the user's catalog, containing all the studies the user has a role on.

Throws:

ServiceException

createStudy

public Study createStudy()
                  throws ServiceException

Create a default study and add it to the user's catalog of studies.

Returns:

a reference to a newly-created study with default name, type, status, and visibility. (Note that the name will be an empty string.) The study identifier, owner identifier, and owner name are initialized, as well as references to study components.

Throws:

ServiceException

createStudy

public Study createStudy(java.lang.String studyName)
                  throws ServiceException

Create a named study and add it to the user's catalog of studies.

Parameters:

studyName - specifies the study name.

Returns:

a reference to a newly-created study with name as specified by the parameter, and default type, status, and visibility. The study identifier, owner identifier, and owner name are initialized, as well as references to study components.

Throws:

ServiceException

createStudy

public Study createStudy(java.lang.String studyName,
                         Study.Type studyType)
                  throws ServiceException

Create a study with specified name and type and add it to the user's catalog of studies.

Parameters:

studyName - specifies the study name.

studyType - specifies the study type.

Returns:

a reference to a newly-created study with name and type as specified by the parameters, and default status and visibility. The study identifier, owner identifier, and owner name are initialized, as well as references to study components.

Throws:

ServiceException

createStudy

public Study createStudy(java.lang.String studyName,
                         Study.Type studyType,
                         Study.Status studyStatus,
                         Study.Visibility studyVisibility)
                  throws ServiceException

Create a study with specified name, type, status, and visibility, and add it to the user's catalog of studies.

Parameters:

studyName - specifies the study name.

studyType - specifies the study type.

studyStatus - specifies the study status.

studyVisibility - specifies the study visibility.

Returns:

a reference to a newly-created study with name, type, status, and visibility as specified by the parameters. The study identifier, owner identifier, and owner name are initialized, as well as references to study components.

Throws:

ServiceException

updateStudy

public Study updateStudy(java.lang.String studyId,
                         java.lang.String studyName)
                  throws ServiceException

Update a study, changing the study name.

Parameters:

studyId - specifies the identifier of the study to update.

studyName - is the new name to assign to the study.

Returns:

a reference to the Study specified by studyId, with its name changed to studyName. The name is also changed on the server.

Throws:

ServiceException

updateStudy

public Study updateStudy(java.lang.String studyId,
                         Study.Status studyStatus)
                  throws ServiceException

Update a study, changing the status.

Parameters:

studyId - specifies the identifier of the study to update.

studyStatus - is the new status to assign to the study.

Returns:

a reference to the Study specified by studyId, with its status changed to studyStatus. The status is also changed on the server.

Throws:

ServiceException

updateStudy

public Study updateStudy(java.lang.String studyId,
                         Study.Visibility studyVisibility)
                  throws ServiceException

Update a study, changing the visibility.

Parameters:

studyId - specifies the identifier of the study to update.

studyVisibility - is the new visibility to assign to the study.

Returns:

a reference to the Study specified by studyId, with its visibility changed to studyVisibility. The visibility is also changed on the server.

Throws:

ServiceException

obtainStudy

public Study obtainStudy(java.lang.String studyId)
                  throws ServiceException

Obtain a study from the server.

Parameters:

studyId - specifies the identifier of the study to obtain.

Returns:

a reference to a study obtained from the server with study identifier equal to studyId.

Throws:

ServiceException

deleteStudy

public void deleteStudy(java.lang.String studyId)
                 throws ServiceException

Delete a study from the server.

Parameters:

studyId - specifies the identifier of the study to delete.

Throws:

ServiceException

obtainRoster

public Roster obtainRoster(java.lang.String studyId)
                    throws ServiceException

Obtain the roster for a study.

Parameters:

studyId - specifies the identifier of the study whose roster is to be obtained.

Returns:

a reference to the roster for the study specified by the input parameter.

Throws:

ServiceException

createRole

public Role createRole(Role role)
                throws ServiceException

Add a Role to a study's roster.

Parameters:

role - the role to add to the roster. The user identifier and study identifier fields of the role must be set. The role is added to the roster of the study, specifying the privileges of the user on the study.

Returns:

a reference to a newly-created role corresponding to the input role with additional fields filled out by the service.

Throws:

ServiceException

updateRole

public Message updateRole(Role role)
                   throws ServiceException

Update a role on the server.

Parameters:

role - specifies the role to change.

Returns:

the role on the server is updated with the fields specified by the input parameter role. A null return value indicates there were no issues with the update. A non-null return value is a reference to a Message which describes how the request was completed provisionally. This happens, e.g., when an attempt is made by user U to change the delete_role privilege on a study owned by user U. The privilege is left unchanged in such cases to ensure that there is always at least one user (the study creator) who is authorized to reset privileges for any roleholder for the study.

Throws:

ServiceException

obtainRole

public Role obtainRole(java.lang.String userId,
                       java.lang.String studyId)
                throws ServiceException

Obtain a role. The role of a specific user on a specific study is obtained.

Parameters:

userId - specifies the user.

studyId - specifies the study.

Returns:

a reference to the role of the specified user on the specified study.

Throws:

ServiceException

deleteRole

public void deleteRole(java.lang.String userId,
                       java.lang.String studyId)
                throws ServiceException

Delete a role. The role played on by a specific user on a specific study is deleted.

Parameters:

userId - specifies the user.

studyId - specifies the study.

Throws:

ServiceException

describePredictors

public void describePredictors(java.lang.String studyId,
                               java.util.List<Predictor> predictorList)
                        throws ServiceException

Describe a study's predictors. A list of column definitions is associated with a study.

Parameters:

studyId - specifies the study whose predictors are to be described.

predictorList - a list of the predictors (= variables = columns) for the table.

Throws:

ServiceException

loadSubjects

public void loadSubjects(java.lang.String studyId,
                         java.util.List<Specimen> specimenList)
                  throws ServiceException

Populate the rows of a study's table with subjects. A list of rows is inserted into the study's table.

Parameters:

studyId - specifies the study whose table is to be populated.

specimenList - a list of the specimens (= rows = observations = records) for the table.

Throws:

ServiceException

scoreProspects

public void scoreProspects(java.lang.String studyId,
                           java.util.List<Specimen> specimenList)
                    throws ServiceException

Score prospects (compute predictands) using a study's model.

Parameters:

studyId - specifies the study whose model is to be used.

specimenList - is the list of specimens (= rows = observations = records) whose predictands are to be computed. Upon return from this method, the predictand member of each Specimen in the list contains the results of the computations (the score).

Throws:

ServiceException