com.yosokumo.core
Class Service

java.lang.Object
  extended by 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.
 
Field Summary
private  Catalog cachedCatalog
          A cached copy of the user's catalog, providing fast access to all studies managed by the catalog.
private  java.lang.String contentType
           
private  Credentials credentials
           
private  Service.DIFType dif
           
private  ServiceException exception
           
private  java.lang.String hostName
           
private  boolean invalidStatusCode
           
private static int MAX_ITEMS_TO_SEND_VIA_HTTP
           
private  java.lang.String methodName
           
private  int port
           
private  boolean refreshedCachedCatalog
          An output from mapStudyIdentifierToStudy.
private  int[][] validStatusCode
           
private  YosokumoDIF ydif
           
private  YosokumoRequest yRequest
           
 
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.
private  Role createRoleX(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.
(package private)  Study createStudy(Study study)
          Create a study and add it to the user's catalog of studies.
private  Study createStudyX()
          Create a default study and add it to the user's catalog of studies.
private  Study createStudyX(java.lang.String studyName)
          Create a named study and add it to the user's catalog of studies.
private  Study createStudyX(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.
private  Study createStudyX(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.
private  boolean deleteRoleX(java.lang.String userId, java.lang.String studyId)
          Delete a role.
 void deleteStudy(java.lang.String studyId)
          Delete a study from the server.
private  boolean deleteStudyX(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.
private  boolean describePredictorsX(java.lang.String studyId, java.util.List<Predictor> predictorList)
          Describe a study's table.
(package private)  ServiceException getException()
          Return Service exception.
private  Role getRoleHelper(java.lang.String userId, java.lang.String studyId)
          Get the role of a specific user on a specific study.
 int getStatusCode()
          Return the status code from the last Service operation.
private  void initDifAndRequest()
          Initialize DIF processor and HTTP request processor.
private  void initForOperation(java.lang.String methodName)
          Initialize for an HTTP operation.
 void loadSubjects(java.lang.String studyId, java.util.List<Specimen> specimenList)
          Populate the rows of a study's table with subjects.
private  boolean loadSubjectsX(java.lang.String studyId, java.util.List<Specimen> specimenList)
          Populate the rows of a study's table.
private  Study mapStudyIdentifierToStudy(java.lang.String studyId)
          Get the study corresponding to a study id.
private  Study mergePanelIntoStudy(Study study)
          Merge the panel data for a study into the Study object itself.
 Catalog obtainCatalog()
          Obtain the user's catalog of studies.
private  Catalog obtainCatalogX()
          Obtain the user's catalog of studies.
 Role obtainRole(java.lang.String userId, java.lang.String studyId)
          Obtain a role.
private  Role obtainRoleX(java.lang.String userId, java.lang.String studyId)
          Obtain a role.
 Roster obtainRoster(java.lang.String studyId)
          Obtain the roster for a study.
private  Roster obtainRosterX(java.lang.String studyId)
          Obtain the roster for a study.
 Study obtainStudy(java.lang.String studyId)
          Obtain a study from the server.
private  Study obtainStudyX(java.lang.String studyId)
          Obtain a study from the server.
private  boolean postEmptyBlock(java.lang.String studyId, java.lang.String uri, Role.Privilege operation)
          Post an empty block to the service.
private  int postSpecimenBlock(Study study, java.util.List<Specimen> specimenList, int firstIdx, int numSpecimensToTransmit, boolean postToTable)
          Post a specimen block to a study's table or model.
private  boolean postSpecimens(java.lang.String studyId, java.util.List<Specimen> specimenList, boolean postToTable)
          Post specimens to a study's table or model.
private  java.lang.Object reportProblem()
          Set up a ServiceException describing a problem detected by the service.
private  java.lang.Object reportProblem(java.lang.String errMess)
          Set up a ServiceException describing a problem detected by the service.
private  boolean requestOk(Role.Privilege operation)
          Check the status code returned by an HTTP request.
 void scoreProspects(java.lang.String studyId, java.util.List<Specimen> specimenList)
          Score prospects (compute predictands) using a study's model.
private  boolean scoreProspectsX(java.lang.String studyId, java.util.List<Specimen> specimenList)
          Score prospects (compute predictands) using a study's model.
(package private)  void setTrace(boolean traceOn)
          Set the trace flag.
 Message updateRole(Role role)
          Update a role on the server.
private  Role updateRoleX(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.
private  Study updateStudyX(java.lang.String studyId, java.lang.String studyName)
          Update a study, changing the study name.
private  Study updateStudyX(java.lang.String studyId, Study.Status studyStatus)
          Update a study, changing the status.
private  Study updateStudyX(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
 

Field Detail

validStatusCode

private int[][] validStatusCode

MAX_ITEMS_TO_SEND_VIA_HTTP

private static final int MAX_ITEMS_TO_SEND_VIA_HTTP
See Also:
Constant Field Values

credentials

private Credentials credentials

hostName

private java.lang.String hostName

port

private int port

dif

private Service.DIFType dif

contentType

private java.lang.String contentType

yRequest

private YosokumoRequest yRequest

ydif

private YosokumoDIF ydif

exception

private ServiceException exception

methodName

private java.lang.String methodName

invalidStatusCode

private boolean invalidStatusCode

cachedCatalog

private Catalog cachedCatalog
A cached copy of the user's catalog, providing fast access to all studies managed by the catalog. The Service API presented to the outer world uses identifiers, not URIs, to specify the objects to operate on. However, all interaction with the Yosokumo server uses URIs. To map from identifiers to URIs, a cachedCatalog is maintained. As an example of how it is used, here is the logic for obtaining a study from the server:


refreshedCachedCatalog

private boolean refreshedCachedCatalog
An output from mapStudyIdentifierToStudy. When true it means that mapStudyIdentifierToStudy refreshed the cached catalog, and when false it means that mapStudyIdentifierToStudy did not refresh the cached catalog.

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

initDifAndRequest

private void initDifAndRequest()
                        throws ServiceException
Initialize DIF processor and HTTP request processor. The input dif is used to instantiate a DIF processor in ydif, as well as contentType. In addition, yRequest is set to an instance of YosokumoRequest for processing HTTP requests.

Throws:
ServiceException - if the DIF is not implemented

initForOperation

private void initForOperation(java.lang.String methodName)
Initialize for an HTTP operation. Init various data fields to prepare for execution of a service request.

Parameters:
methodName - is the name of the service method being executed, e.g., "obtainCatalog". It is used in messages if an error occurs.

requestOk

private boolean requestOk(Role.Privilege operation)
Check the status code returned by an HTTP request.

Parameters:
operation - specifies the HTTP request, e.g. GET_STUDY.
Returns:
is true if and only if the status code is 2xx and the validStatusCode table indicates the status code value is allowed for the operation. In all other cases, false is returned to indicate that the request was not successfully performed. In addition the data member invalidStatusCode is set true if and only if one of these conditions holds: 1) the status code is 2xx or 4xx and validStatusCode table indicates the status code value is not allowed for the operation, or 2) the status code is not 5xx.

setTrace

void setTrace(boolean traceOn)
Set the trace flag.

Parameters:
traceOn - setting to turn on or off trace output of HTTP requests.

getException

ServiceException getException()
Return Service exception.

Returns:
exception occurring during HTTP processing. Null means none.

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

obtainCatalogX

private Catalog obtainCatalogX()
Obtain the user's catalog of studies.

Returns:
null means the user's catalog could not be obtained (call getException() for details). Otherwise the return value is a reference to the user's catalog, containing all the studies the user has a role on.

createStudyX

private Study createStudyX()
Create a default study and add it to the user's catalog of studies.

Returns:
null means the study could not be created (call getException() for details). Otherwise the return value is 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.

createStudyX

private Study createStudyX(java.lang.String studyName)
Create a named study and add it to the user's catalog of studies.

Parameters:
studyName - specifies the study name.
Returns:
null means the study could not be created (call getException() for details). Otherwise the return value is 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.

createStudyX

private Study createStudyX(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.

Parameters:
studyName - specifies the study name.
studyType - specifies the study type.
Returns:
null means the study could not be created (call getException() for details). Otherwise the return value is 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.

createStudyX

private Study createStudyX(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.

Parameters:
studyName - specifies the study name.
studyType - specifies the study type.
studyStatus - specifies the study status.
studyVisibility - specifies the study visibility.
Returns:
null means the study could not be created (call getException() for details). Otherwise the return value is 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.

updateStudyX

private Study updateStudyX(java.lang.String studyId,
                           java.lang.String studyName)
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:
null means the study could not be changed (call getException() for details). Otherwise the return value is the Study specified by studyId, with its name changed to studyName. The name is also changed on the server.

updateStudyX

private Study updateStudyX(java.lang.String studyId,
                           Study.Status studyStatus)
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:
null means the study could not be changed (call getException() for details). Otherwise the return value is the Study specified by studyId, with its status changed to studyStatus. The status is also changed on the server.

updateStudyX

private Study updateStudyX(java.lang.String studyId,
                           Study.Visibility studyVisibility)
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:
null means the study could not be changed (call getException() for details). Otherwise the return value is the Study specified by studyId, with its visibility changed to studyVisibility. The visibility is also changed on the server.

obtainStudyX

private Study obtainStudyX(java.lang.String studyId)
Obtain a study from the server.

Parameters:
studyId - specifies the identifier of the study to obtain.
Returns:
null means the study could not be obtained (call getException() for details). Otherwise the return value is a reference to a study obtained from the server with study identifier == studyId.

deleteStudyX

private boolean deleteStudyX(java.lang.String studyId)
Delete a study from the server.

Parameters:
studyId - specifies the identifier of the study to delete.
Returns:
false means the study could not be deleted (call getException() for details). true means the study was deleted.

obtainRosterX

private Roster obtainRosterX(java.lang.String studyId)
Obtain the roster for a study.

Parameters:
studyId - specifies the identifier of the study whose roster is to be obtained.
Returns:
null means the roster could not be obtained (call getException() for details). Otherwise the return value is a reference to the roster for the study specified by the input parameter.

createRoleX

private Role createRoleX(Role role)
Add a Role to a study's roster.

Parameters:
role - the role to add to the roster. The user identifier and study identifier fields must be set. The role is added to the roster of the study, specifying the privileges of the user on the study.
Returns:
null means the role could not be created (call getException() for details). Otherwise the return value is a reference to a newly-created role corresponding to the input role with additional fields filled out by the service.

updateRoleX

private Role updateRoleX(Role role)
Update a role on the server.

Parameters:
role - specifies the role to change.
Returns:
null means the role could not be changed (call getException() for details). Otherwise the return value is the input parameter role and all the fields for role have been changed on the server.

obtainRoleX

private Role obtainRoleX(java.lang.String userId,
                         java.lang.String studyId)
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:
null means the role could not be obtained (call getException() for details). Otherwise the return value is a reference to the role of the specified user on the specified study.

deleteRoleX

private boolean deleteRoleX(java.lang.String userId,
                            java.lang.String studyId)
Delete a role. The role of a specific user on a specific study is deleted.

Parameters:
userId - specifies the user.
studyId - specifies the study.
Returns:
false means the role could not be deleted (call getException() for details). true means the role played on the user specified by userId on the study specified by studyId was deleted.

describePredictorsX

private boolean describePredictorsX(java.lang.String studyId,
                                    java.util.List<Predictor> predictorList)
Describe a study's table. A list of column definitions is associated with a study.

Parameters:
studyId - specifies the study whose table is to be described.
predictorList - a list of the predictors (= variables = columns) for the table.
Returns:
false means the table description failed (call getException() for details). true means the study's table was successfully described.

loadSubjectsX

private boolean loadSubjectsX(java.lang.String studyId,
                              java.util.List<Specimen> specimenList)
Populate the rows of a study's table. A list of rows is inserted into a 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.
Returns:
false means the table population failed (call getException() for details). true means the study's table was successfully populated with rows.

scoreProspectsX

private boolean scoreProspectsX(java.lang.String studyId,
                                java.util.List<Specimen> specimenList)
Score prospects (compute predictands) using a study's model.

Parameters:
studyId - specifies the study whose model is to be used.
specimenList - a list of specimens (= rows = observations = records) whose predictands are to be computed.
Returns:
false means the predictand computation failed (call getException() for details). true means the predictand computations were succesful; the predictand members of each Specimen in the list contain the results of the computations.

postSpecimens

private boolean postSpecimens(java.lang.String studyId,
                              java.util.List<Specimen> specimenList,
                              boolean postToTable)
Post specimens to a study's table or model. In the former case, the rows of the table are populated with the specimens, and in the latter case the specimens are scored.

Parameters:
studyId - specifies the study to post to.
specimenList - is a list of the specimens (= rows = observations = records) to post.
postToTable - indicates whether to post to the study's table or model.
Returns:
false means the post operation failed (call getException() for details). true means the post operation succeeded.

postEmptyBlock

private boolean postEmptyBlock(java.lang.String studyId,
                               java.lang.String uri,
                               Role.Privilege operation)
Post an empty block to the service.

Parameters:
studyId - specifies the study to which to post the empty block.
uri - is either the table location or the model location of the study.
operation - is either Role.Privilege.POST_TABLE or Role.Privilege.POST_MODEL, agreeing with the uri.
Returns:
false means the post failed (call getException() for details). true means an empty block was successfully posted.

postSpecimenBlock

private int postSpecimenBlock(Study study,
                              java.util.List<Specimen> specimenList,
                              int firstIdx,
                              int numSpecimensToTransmit,
                              boolean postToTable)
Post a specimen block to a study's table or model. In the former case, the rows of the table are populated with the specimen block, and in the latter case the specimens in the block are scored.

Parameters:
study - specifies the study to post to.
specimenList - is a list of the specimens (= rows = observations = records) from which the specimen block is constructed.
firstIdx - (>= 0) is an index to the first element in specimenList to include in the specimen block.
numSpecimensToTransmit - (>= 0) is the number of specimens to include in the block.
postToTable - indicates whether to post to the study's table or model.
Returns:
-1 means the post operation failed (call getException() for details). >= 0 means the post operation succeeded, and the return value is an index to the first element in specimenList which was not part of the posted block.

createStudy

Study createStudy(Study study)
Create a study and add it to the user's catalog of studies.

Parameters:
study - specifies the name, type, status, and visibility of the new study to create. The type can never be changed.
Returns:
null means the study could not be created (call getException() for details). Otherwise the return value is a reference to a newly-created study with name, type, status, and visibility as specified by the input parameter. The study identifier, owner identifier, and owner name are initialized, as well as various references.

mergePanelIntoStudy

private Study mergePanelIntoStudy(Study study)
Merge the panel data for a study into the Study object itself.

Parameters:
study - specifies the study to change.
Returns:
null means the panel merge was not successful (call getException() for details). Otherwise the return value is the input parameter study with all the fields from the study's panel merged into the corresponding fields in the Study object.

getRoleHelper

private Role getRoleHelper(java.lang.String userId,
                           java.lang.String studyId)
Get the role of a specific user on a specific study.

Parameters:
userId - specifies the user.
studyId - specifies the study.
Returns:
null means the role could not be obtained. Otherwise the return value is the role of the specified user on the specified study.

mapStudyIdentifierToStudy

private Study mapStudyIdentifierToStudy(java.lang.String studyId)
Get the study corresponding to a study id. Whenever possible, the study is obtained from the cached catalog.

Parameters:
studyId - specifies the study to get.
Returns:
null means the study could not be obtained. Otherwise the return value is the Study specified by studyId. Note that the boolean refreshedCachedCatalog is set to indicate if this method refreshed the cached catalog or not.

reportProblem

private java.lang.Object reportProblem()
Set up a ServiceException describing a problem detected by the service.

Returns:
null in all cases. The field exception is set to a ServiceException with a message constructed from a pre-existing exception, a Message object in the HTTP entity, and/or the HTTP status code.

reportProblem

private java.lang.Object reportProblem(java.lang.String errMess)
Set up a ServiceException describing a problem detected by the service.

Parameters:
errMess - is the prefix to use in an error message.
Returns:
null in all cases. The field exception is set to a ServiceException with a message constructed from a pre-existing exception, a Message object in the HTTP entity, and/or the HTTP status code.