|
||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object com.yosokumo.core.Service
public class Service
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 |
---|
private int[][] validStatusCode
private static final int MAX_ITEMS_TO_SEND_VIA_HTTP
private Credentials credentials
private java.lang.String hostName
private int port
private Service.DIFType dif
private java.lang.String contentType
private YosokumoRequest yRequest
private YosokumoDIF ydif
private ServiceException exception
private java.lang.String methodName
private boolean invalidStatusCode
private Catalog cachedCatalog
cachedCatalog
is maintained. As an example of how it is
used, here is the logic for obtaining a study from the server:
private boolean refreshedCachedCatalog
Constructor Detail |
---|
public Service() throws ServiceException
Service
object using defaults for
the credentials, host name, port, and DIF.
ServiceException
public Service(Credentials credentials) throws ServiceException
Service
object with attributes
specified by the input parameters, using defaults for the host name,
port, and DIF.
credentials
- user id and key for authentication.
ServiceException
public Service(Credentials credentials, java.lang.String hostName) throws ServiceException
Service
object with attributes
specified by the input parameters, using defaults for the port and DIF.
credentials
- user id and key for authentication.hostName
- host name for the Yosokumo server.
ServiceException
public Service(Credentials credentials, java.lang.String hostName, int port) throws ServiceException
Service
object with attributes
specified by the input parameters, using a default for the DIF.
credentials
- user id and key for authentication.hostName
- host name for the Yosokumo server.port
- port to use for HTTP communication.
ServiceException
public Service(Credentials credentials, java.lang.String hostName, int port, Service.DIFType dif) throws ServiceException
Service
object with attributes
specified by the input 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.
ServiceException
- if the DIF is not implementedMethod Detail |
---|
private void initDifAndRequest() throws ServiceException
ServiceException
- if the DIF is not implementedprivate void initForOperation(java.lang.String methodName)
methodName
- is the name of the service method being executed,
e.g., "obtainCatalog". It is used in messages if an error
occurs.private boolean requestOk(Role.Privilege operation)
operation
- specifies the HTTP request, e.g. GET_STUDY.
void setTrace(boolean traceOn)
traceOn
- setting to turn on or off trace output of HTTP
requests.ServiceException getException()
public int getStatusCode()
public Catalog obtainCatalog() throws ServiceException
ServiceException
public Study createStudy() throws ServiceException
ServiceException
public Study createStudy(java.lang.String studyName) throws ServiceException
studyName
- specifies the study name.
ServiceException
public Study createStudy(java.lang.String studyName, Study.Type studyType) throws ServiceException
studyName
- specifies the study name.studyType
- specifies the study type.
ServiceException
public Study createStudy(java.lang.String studyName, Study.Type studyType, Study.Status studyStatus, Study.Visibility studyVisibility) throws ServiceException
studyName
- specifies the study name.studyType
- specifies the study type.studyStatus
- specifies the study status.studyVisibility
- specifies the study visibility.
ServiceException
public Study updateStudy(java.lang.String studyId, java.lang.String studyName) throws ServiceException
studyId
- specifies the identifier of the study to update.studyName
- is the new name to assign to the study.
Study
specified by studyId, with
its name changed to studyName. The name is also changed on
the server.
ServiceException
public Study updateStudy(java.lang.String studyId, Study.Status studyStatus) throws ServiceException
studyId
- specifies the identifier of the study to update.studyStatus
- is the new status to assign to the study.
Study
specified by studyId, with
its status changed to studyStatus. The status is also changed
on the server.
ServiceException
public Study updateStudy(java.lang.String studyId, Study.Visibility studyVisibility) throws ServiceException
studyId
- specifies the identifier of the study to update.studyVisibility
- is the new visibility to assign to the study.
Study
specified by studyId, with
its visibility changed to studyVisibility. The visibility is
also changed on the server.
ServiceException
public Study obtainStudy(java.lang.String studyId) throws ServiceException
studyId
- specifies the identifier of the study to obtain.
ServiceException
public void deleteStudy(java.lang.String studyId) throws ServiceException
studyId
- specifies the identifier of the study to delete.
ServiceException
public Roster obtainRoster(java.lang.String studyId) throws ServiceException
studyId
- specifies the identifier of the study whose roster
is to be obtained.
ServiceException
public Role createRole(Role role) throws ServiceException
Role
to a study's roster.
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.
ServiceException
public Message updateRole(Role role) throws ServiceException
role
- specifies the role to change.
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.
ServiceException
public Role obtainRole(java.lang.String userId, java.lang.String studyId) throws ServiceException
userId
- specifies the user.studyId
- specifies the study.
ServiceException
public void deleteRole(java.lang.String userId, java.lang.String studyId) throws ServiceException
userId
- specifies the user.studyId
- specifies the study.
ServiceException
public void describePredictors(java.lang.String studyId, java.util.List<Predictor> predictorList) throws ServiceException
studyId
- specifies the study whose predictors are to be
described.predictorList
- a list of the predictors (= variables = columns)
for the table.
ServiceException
public void loadSubjects(java.lang.String studyId, java.util.List<Specimen> specimenList) throws ServiceException
studyId
- specifies the study whose table is to be populated.specimenList
- a list of the specimens
(= rows = observations = records) for the table.
ServiceException
public void scoreProspects(java.lang.String studyId, java.util.List<Specimen> specimenList) throws ServiceException
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).
ServiceException
private Catalog obtainCatalogX()
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.private Study createStudyX()
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.private Study createStudyX(java.lang.String studyName)
studyName
- specifies the study name.
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.private Study createStudyX(java.lang.String studyName, Study.Type studyType)
studyName
- specifies the study name.studyType
- specifies the study type.
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.private Study createStudyX(java.lang.String studyName, Study.Type studyType, Study.Status studyStatus, Study.Visibility studyVisibility)
studyName
- specifies the study name.studyType
- specifies the study type.studyStatus
- specifies the study status.studyVisibility
- specifies the study visibility.
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.private Study updateStudyX(java.lang.String studyId, java.lang.String studyName)
studyId
- specifies the identifier of the study to update.studyName
- is the new name to assign to the study.
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.private Study updateStudyX(java.lang.String studyId, Study.Status studyStatus)
studyId
- specifies the identifier of the study to update.studyStatus
- is the new status to assign to the study.
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.private Study updateStudyX(java.lang.String studyId, Study.Visibility studyVisibility)
studyId
- specifies the identifier of the study to update.studyVisibility
- is the new visibility to assign to the study.
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.private Study obtainStudyX(java.lang.String studyId)
studyId
- specifies the identifier of the study to obtain.
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.private boolean deleteStudyX(java.lang.String studyId)
studyId
- specifies the identifier of the study to delete.
false
means the study could not be deleted (call
getException()
for details).
true
means the study was deleted.private Roster obtainRosterX(java.lang.String studyId)
studyId
- specifies the identifier of the study whose roster
is to be obtained.
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.private Role createRoleX(Role role)
Role
to a study's roster.
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.
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.private Role updateRoleX(Role role)
role
- specifies the role to change.
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.private Role obtainRoleX(java.lang.String userId, java.lang.String studyId)
userId
- specifies the user.studyId
- specifies the study.
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.private boolean deleteRoleX(java.lang.String userId, java.lang.String studyId)
userId
- specifies the user.studyId
- specifies the study.
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.private boolean describePredictorsX(java.lang.String studyId, java.util.List<Predictor> predictorList)
studyId
- specifies the study whose table is to be described.predictorList
- a list of the predictors (= variables = columns)
for the table.
false
means the table description failed (call
getException()
for details).
true
means the study's table was successfully
described.private boolean loadSubjectsX(java.lang.String studyId, java.util.List<Specimen> specimenList)
studyId
- specifies the study whose table is to be populated.specimenList
- a list of the specimens
(= rows = observations = records) for the table.
false
means the table population failed (call
getException()
for details).
true
means the study's table was successfully
populated with rows.private boolean scoreProspectsX(java.lang.String studyId, java.util.List<Specimen> specimenList)
studyId
- specifies the study whose model is to be used.specimenList
- a list of specimens
(= rows = observations = records) whose predictands
are to be computed.
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.private boolean postSpecimens(java.lang.String studyId, java.util.List<Specimen> specimenList, boolean postToTable)
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.
getException()
for details).
true means the post operation succeeded.private boolean postEmptyBlock(java.lang.String studyId, java.lang.String uri, Role.Privilege operation)
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.
false
means the post failed (call
getException()
for details).
true
means an empty block was successfully posted.private int postSpecimenBlock(Study study, java.util.List<Specimen> specimenList, int firstIdx, int numSpecimensToTransmit, boolean postToTable)
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.
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.Study createStudy(Study study)
study
- specifies the name, type, status, and visibility of the
new study to create. The type can never be changed.
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.private Study mergePanelIntoStudy(Study study)
Study
object itself.
study
- specifies the study to change.
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.private Role getRoleHelper(java.lang.String userId, java.lang.String studyId)
userId
- specifies the user.studyId
- specifies the study.
null
means the role could not be obtained.
Otherwise the return value is the role
of the
specified user on the specified study.private Study mapStudyIdentifierToStudy(java.lang.String studyId)
studyId
- specifies the study to get.
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.private java.lang.Object reportProblem()
ServiceException
describing a problem detected by
the service.
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.private java.lang.Object reportProblem(java.lang.String errMess)
ServiceException
describing a problem detected by
the service.
errMess
- is the prefix to use in an error message.
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.
|
||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |