edu.indiana.dde.mylead.client
Class LeadClient

java.lang.Object
  extended byedu.indiana.dde.mylead.client.LeadClient
All Implemented Interfaces:
LeadClientIntf

public class LeadClient
extends java.lang.Object
implements LeadClientIntf

This class implements the LeadClientIntf interface and is the means by which users of the myLEAD metadata catalog interface with the database. This class contains methods for adding data to the catalog and querying the catalog.

This class was initially based on the MCSClient class.

See Also:
org.globus.mcs.client.dai.MCSClient

Constructor Summary
LeadClient(java.lang.String gridserviceurl, java.lang.String gridfactoryurl, java.lang.String gridregistryurl)
          Constructor for the LeadClient object using the default lifetime.
LeadClient(java.lang.String gridserviceurl, java.lang.String gridfactoryurl, java.lang.String gridregistryurl, int servicetime)
          Constructor for the LeadClient object.
 
Method Summary
 org.globus.mcs.common.ReturnType addAttribute(java.lang.String dn, MyLeadAttrData attribute, java.lang.String parentName, java.lang.String parentType)
          This method takes a MyLeadAttrData object and adds it to the object specified by the parent name passed as a parameter.
 org.globus.mcs.common.ReturnType attributeDef(java.lang.String dn, LeadStringHolder attrDef)
          This method returns an XML fragment containing the attributes and elements defined in the mcs_lead database for myLEAD.
 void close()
          Closes the grid service connection and destroys the service instance.
 org.globus.mcs.common.ReturnType create(java.lang.String dn, MyLeadData item)
          This method takes an object that extends MyLeadData (since MyLeadData is an abstract class) and adds that item to the database.
 org.globus.mcs.common.ReturnType create(java.lang.String dn, MyLeadData item, java.lang.String parentName, java.lang.String parentType)
          This version of the create method has additional parameters for the name of the parent object this item is being added to as well as the parent's type.
 org.globus.mcs.common.ReturnType create(java.lang.String dn, MyLeadReplica replica)
          This method overrides the create method to take an instance of MyLeadReplica which is used to add a new record for a myLEAD replica to the database.
 org.globus.mcs.common.ReturnType create(java.lang.String dn, MyLeadUser user)
          This method overrides the create method to take an instance of a MyLeadUser object to add a user profile to the mcs_writer table.
protected  void finalize()
           
protected static java.lang.String getEnvironmentVar(java.lang.String var)
          Used to determine the value for an environment variable.
 org.globus.mcs.common.ReturnType getNotifications(java.lang.String dn, java.lang.String expName, LeadStringHolder results)
          Deprecated. As of version 0.3 Alpha - instead use queryLead with the TARGET_ATTR filter.
 java.lang.String getServiceUrl()
          This method returns the endpoint url of the service that is currently being accessed.
 org.globus.mcs.common.ReturnType getWorkflowInstances(java.lang.String dn, java.lang.String expName, LeadStringHolder results)
          Deprecated. As of version 0.3 Alpha - instead use queryLead with the TARGET_ATTR filter.
 org.globus.mcs.common.ReturnType getWorkflowTemplates(java.lang.String dn, java.lang.String invName, LeadStringHolder results)
          Deprecated. As of version 0.3 Alpha - instead use queryLead with the TARGET_ATTR filter.
 boolean isAuthenticated()
          This method allows the user to find out whether this client is working in authenticated mode.
 org.globus.mcs.common.ReturnType queryLead(java.lang.String dn, int limit, java.lang.String filter, MyLeadQuery target, LeadStringHolder results)
          Query myLEAD projects, experiments, collections, or logical files based on both system-defined and complex attributes, but based only on a target object and not the context of that object.
 org.globus.mcs.common.ReturnType queryLead(java.lang.String dn, int limit, java.lang.String filter, MyLeadQuery target, MyLeadContextQuery query, LeadStringHolder results)
          Query myLEAD based on a target specification for a file, collection, experiment, or project in the context of a query composed of chains of objects that could be contained in the target or objects the target is within.
 org.globus.mcs.common.ReturnType queryReplica(java.lang.String dn, LeadStringHolder results)
          This method is passed the distinguished name (dn) of the user and returns information regarding the myLEAD replica that user is assigned to in the mcs_writer table.
 org.globus.mcs.common.ReturnType queryUser(java.lang.String dn, LeadStringHolder results)
          This method is passed the distinguished name (dn) of the user and returns information regarding the myLEAD profile for that user in the mcs_writer table.
 void setAuthentication(boolean authentic)
          This method allows you to make an authenticated connection to the myLEAD service.
 org.globus.mcs.common.ReturnType update(java.lang.String dn, MyLeadReplica replica)
          This method takes an instance of MyLeadReplica which is used to update an existing myLEAD replica definition in the database based on the nickname.
 org.globus.mcs.common.ReturnType update(java.lang.String dn, MyLeadUser user)
          This method takes an instance of MyLeadUser which is used to update an existing myLEAD user profile in the mcs_writer table.
 org.globus.mcs.common.ReturnType userExists(java.lang.String dn)
          This method is passed a distinguished name and it either returns OPERATION_SUCCESSFUL if the user exists in the myLEAD catalog, or it returns NO_RESULTS_FOUND if the user is not defined in myLEAD.
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

LeadClient

public LeadClient(java.lang.String gridserviceurl,
                  java.lang.String gridfactoryurl,
                  java.lang.String gridregistryurl,
                  int servicetime)
           throws org.globus.mcs.client.MCSException
Constructor for the LeadClient object. It takes in 4 arguments as listed below.
At least one of the URL arguments has to be NON NULL for the object to be created.

Parameters:
gridserviceurl - The url string where the service instance is located.
gridfactoryurl - The url string where the factory instance can be located.
gridregistryurl - The url string where the registry can be located.
servicetime - The destroy time for the service instance which is created using a factory.
Throws:
org.globus.mcs.client.MCSException - If any error occurs then this exception is thrown.
See Also:
MCSException

LeadClient

public LeadClient(java.lang.String gridserviceurl,
                  java.lang.String gridfactoryurl,
                  java.lang.String gridregistryurl)
           throws org.globus.mcs.client.MCSException
Constructor for the LeadClient object using the default lifetime. This version of the constructor takes 3 arguments as listed below.
At least one of the URL arguments has to be NON NULL for the object to be created. The service instance, if created from a factory, will have a default destroy time of 5 minutes.

Parameters:
gridserviceurl - The url string where the service instance is located.
gridfactoryurl - The url string where the factory instance can be located.
gridregistryurl - The url string where the registry can be located.
Throws:
org.globus.mcs.client.MCSException - If any error occurs then this exception is thrown.
See Also:
MCSException
Method Detail

getEnvironmentVar

protected static java.lang.String getEnvironmentVar(java.lang.String var)
                                             throws java.io.IOException
Used to determine the value for an environment variable.

Parameters:
var - String that is the name of the environment variable that we wish to retrieve (e.g., MYLEAD_HOME).
Returns:
String containing the value of the environment variable setting.
Throws:
java.io.IOException - If any error occurs then this exception is thrown.
See Also:
IOException

userExists

public org.globus.mcs.common.ReturnType userExists(java.lang.String dn)
                                            throws org.globus.mcs.client.MCSException
This method is passed a distinguished name and it either returns OPERATION_SUCCESSFUL if the user exists in the myLEAD catalog, or it returns NO_RESULTS_FOUND if the user is not defined in myLEAD.

Specified by:
userExists in interface LeadClientIntf
Parameters:
dn - String with the distinguished name of the user being checked for.
Returns:
ReturnType - Values returned are:
ReturnType.OPERATION_SUCCESSFUL or
ReturnType.NO_RESULTS_FOUND
Throws:
org.globus.mcs.client.MCSException
See Also:
ReturnType

queryLead

public org.globus.mcs.common.ReturnType queryLead(java.lang.String dn,
                                                  int limit,
                                                  java.lang.String filter,
                                                  MyLeadQuery target,
                                                  LeadStringHolder results)
                                           throws org.globus.mcs.client.MCSException
Query myLEAD projects, experiments, collections, or logical files based on both system-defined and complex attributes, but based only on a target object and not the context of that object. The attributes can have elements and also sub-attributes. An object which is derived from the abstract class MyLeadQuery is passed as a parameter. Currently in myLEAD, the derived classes are MyLeadProject, MyLeadExperiment, MyLeadCollection, and MyLeadFile. All four of these classes inherit from the MyLeadQuery abstract class.
As in MCS, the user can specify the number of results they want returned by setting the limit parameter.
When the limit is set to zero, all of the results are returned.
The results are returned in the LeadStringHolder that was passed as a parameter.

Specified by:
queryLead in interface LeadClientIntf
Parameters:
dn - String with the distinguished name of the user issuing the query.
limit - integer that is the number of results that are to be returned.
filter - A String containing one of the filter options.
target - A MyLeadQuery object that is a MyLeadProject, MyLeadExperiment, MyLeadCollection, or MyLeadFile.
results - A LeadStringHolder in which an XML fragment is returned with the results.
Returns:
ReturnType - Values returned are:
ReturnType.OPERATION_SUCCESSFUL,
ReturnType.NO_RESULTS_FOUND, or
ReturnType.MCS_INTERNAL_ERROR
Throws:
org.globus.mcs.client.MCSException - If any error occurs during execution of the request then this Exception is thrown.
See Also:
MyLeadQuery, MyLeadFile, MyLeadCollection, MyLeadExperiment, MyLeadProject, LeadStringHolder, MCSException, ReturnType

queryLead

public org.globus.mcs.common.ReturnType queryLead(java.lang.String dn,
                                                  int limit,
                                                  java.lang.String filter,
                                                  MyLeadQuery target,
                                                  MyLeadContextQuery query,
                                                  LeadStringHolder results)
                                           throws org.globus.mcs.client.MCSException
Query myLEAD based on a target specification for a file, collection, experiment, or project in the context of a query composed of chains of objects that could be contained in the target or objects the target is within. The query consists of one or more chains of objects that are combined conjunctively and/or disjuctively to provide the context for the target specified. Both the target and the query chains can also include criteria for simple static attributes as well as complex dynamic attributes.
The filter parameter allows the user to define what data is returned. The filter options are:
PATH
FULL_SUBTREE
SUBTREE _PATH
TARGET
TARGET_GUIDONLY
TARGET_NOATTR
TARGET_ATTR

FULL_SUBTREE is the same as the result returned by the top level of the query when queryLead is called with just a target in the other version of this method. For each object meeting the criteria specified for the target, in the context of the query chains, the object and all objects and attributes within that object will be returned.
SUBTREE _PATH will return the objects meeting the criteria for the target in the query context, but it will only return those objects within the targets that either meet some of the query chain criteria or are objects on the path between the targets and those objects included because they match the query criteria. Attributes are also included in the result.
TARGET will return only the objects that meet the target criteria within the context of the query chains. No subtree of other objects are returned, but the static and dynamic attributes of the targets are included in the result.
TARGET_GUIDONLY will only return the global ID of the objects meeting the target criteria in the context of the query. No other static or dynamic attributes are included.
TARGET_NOATTR will return the same result as the TARGET option except that only static attributes are included and dynamic attributes are omitted.
TARGET_ATTR will return the dynamic attributes specified in the target criteria for the objects meeting the target criteria in the context of the query. No other static or dynamic attributes are included in the result.

As in MCS, the user can specify the number of results they want returned by setting the limit parameter. The limit is the number of targets included. For example, if the FULL_SUBTREE filter is being used, limit is set to 2, and there are 10 objects matching the target criteria in the context of the query, then the full subtree will be returned for the first two objects matching the target.
When the limit is set to zero, all of the results are returned.
The results are returned in the LeadStringHolder that was passed as a parameter.

Specified by:
queryLead in interface LeadClientIntf
Parameters:
dn - String with the distinguished name of the user issuing the query.
limit - The number of results that are to be returned.
filter - A String containing one of the filter options listed.
target - A string with the criteria for the target object and any static or dynamic attributes to be considered. The object will be a file, collection, experiment, or project.
query - String containing the chains of objects that the target must contain and/or be within. If the query is a blank string, then the results will be based only on the criteria in the target.
results - A LeadStringHolder in which an XML fragment is returned with the results.
Returns:
ReturnType - Values returned are:
ReturnType.OPERATION_SUCCESSFUL,
ReturnType.NO_RESULTS_FOUND, or
ReturnType.MCS_INTERNAL_ERROR
Throws:
org.globus.mcs.client.MCSException - If any error occurs during execution of the request then this Exception is thrown.
See Also:
MyLeadQuery, MyLeadFile, MyLeadCollection, MyLeadExperiment, MyLeadProject, LeadStringHolder, MCSException, ReturnType

queryReplica

public org.globus.mcs.common.ReturnType queryReplica(java.lang.String dn,
                                                     LeadStringHolder results)
                                              throws org.globus.mcs.client.MCSException
This method is passed the distinguished name (dn) of the user and returns information regarding the myLEAD replica that user is assigned to in the mcs_writer table. If an asterisk is passed as the dn, then information regarding all replicas is returned.

Specified by:
queryReplica in interface LeadClientIntf
Parameters:
dn - String with the distinguished name of the user.
results - A LeadStringHolder in which an XML fragment is returned with the results.
Returns:
ReturnType - Values returned are:
ReturnType.OPERATION_SUCCESSFUL, or
ReturnType.NO_RESULTS_FOUND
Throws:
org.globus.mcs.client.MCSException - If an error occurs during execution of request this Exception is thrown.
See Also:
LeadStringHolder, MCSException, ReturnType

queryUser

public org.globus.mcs.common.ReturnType queryUser(java.lang.String dn,
                                                  LeadStringHolder results)
                                           throws org.globus.mcs.client.MCSException
This method is passed the distinguished name (dn) of the user and returns information regarding the myLEAD profile for that user in the mcs_writer table. If an asterisk is passed as the dn, then information regarding all users is returned.

Specified by:
queryUser in interface LeadClientIntf
Parameters:
dn - String with the distinguished name of the user.
results - A LeadStringHolder in which an XML fragment is returned with the results.
Returns:
ReturnType - Values returned are:
ReturnType.OPERATION_SUCCESSFUL, or
ReturnType.NO_RESULTS_FOUND
Throws:
org.globus.mcs.client.MCSException - If an error occurs during execution of request then this Exception is thrown.
See Also:
LeadStringHolder, MCSException, ReturnType

attributeDef

public org.globus.mcs.common.ReturnType attributeDef(java.lang.String dn,
                                                     LeadStringHolder attrDef)
                                              throws org.globus.mcs.client.MCSException
This method returns an XML fragment containing the attributes and elements defined in the mcs_lead database for myLEAD.

Specified by:
attributeDef in interface LeadClientIntf
Parameters:
dn - String with the distinguished name of the user executing the query.
attrDef - A LeadStringHolder in which an XML fragment is returned with the results.
Returns:
ReturnType - Values returned are:
ReturnType.OPERATION_SUCCESSFUL,
ReturnType.NO_RESULTS_FOUND, or
ReturnType.MCS_INTERNAL_ERROR
Throws:
org.globus.mcs.client.MCSException - If an error occurs during execution of the request then this Exception is thrown.
See Also:
MCSException, ReturnType

create

public org.globus.mcs.common.ReturnType create(java.lang.String dn,
                                               MyLeadData item)
                                        throws org.globus.mcs.client.MCSException
This method takes an object that extends MyLeadData (since MyLeadData is an abstract class) and adds that item to the database.

Specified by:
create in interface LeadClientIntf
Parameters:
dn - String with the distinguished name of the user adding the object.
item - A MyLeadFileData, MyLeadCollData, MyLeadExpData, or MyLeadProjData object.
Returns:
ReturnType - Values returned are:
ReturnType.OPERATION_SUCCESSFUL or
ReturnType.AUTHORIZATION_ERROR
Throws:
org.globus.mcs.client.MCSException - If an error occurs during execution of the request then this Exception is thrown.
See Also:
MyLeadFileData, MyLeadCollData, MyLeadExpData, MyLeadProjData, MCSException, ReturnType

create

public org.globus.mcs.common.ReturnType create(java.lang.String dn,
                                               MyLeadData item,
                                               java.lang.String parentName,
                                               java.lang.String parentType)
                                        throws org.globus.mcs.client.MCSException
This version of the create method has additional parameters for the name of the parent object this item is being added to as well as the parent's type.

Specified by:
create in interface LeadClientIntf
Parameters:
dn - String with the distinguished name of the user adding the object.
item - A MyLeadFileData, MyLeadCollData, MyLeadExpData, or MyLeadProjData object.
parentName - String with the name of the parent object this item is being added to.
parentType - String with the type of the parent - must match one of the types from mlAggregationType in the leadActivity schema.
Returns:
ReturnType - Values returned are:
ReturnType.OPERATION_SUCCESSFUL or
ReturnType.AUTHORIZATION_ERROR
Throws:
org.globus.mcs.client.MCSException - If an error occurs during execution of the request then this Exception is thrown.
See Also:
MyLeadFileData, MyLeadCollData, MyLeadExpData, MyLeadProjData, MCSException, ReturnType

create

public org.globus.mcs.common.ReturnType create(java.lang.String dn,
                                               MyLeadReplica replica)
                                        throws org.globus.mcs.client.MCSException
This method overrides the create method to take an instance of MyLeadReplica which is used to add a new record for a myLEAD replica to the database.

Specified by:
create in interface LeadClientIntf
Parameters:
replica - A MyLeadReplica object.
Returns:
ReturnType - Values returned are:
ReturnType.OPERATION_SUCCESSFUL or
ReturnType.AUTHORIZATION_ERROR
Throws:
org.globus.mcs.client.MCSException - If an error occurs during execution of the request then this Exception is thrown.
See Also:
MyLeadReplica, MCSException, ReturnType

update

public org.globus.mcs.common.ReturnType update(java.lang.String dn,
                                               MyLeadReplica replica)
                                        throws org.globus.mcs.client.MCSException
This method takes an instance of MyLeadReplica which is used to update an existing myLEAD replica definition in the database based on the nickname.

Specified by:
update in interface LeadClientIntf
Parameters:
dn - Distinguished name of user requesting the change
replica - A MyLeadReplica object.
Returns:
ReturnType - Values returned are:
ReturnType.OPERATION_SUCCESSFUL, or ReturnType.AUTHORIZATION_ERROR
Throws:
org.globus.mcs.client.MCSException - If an error occurs during execution of the request then this Exception is thrown.
See Also:
MyLeadReplica, MCSException, ReturnType

create

public org.globus.mcs.common.ReturnType create(java.lang.String dn,
                                               MyLeadUser user)
                                        throws org.globus.mcs.client.MCSException
This method overrides the create method to take an instance of a MyLeadUser object to add a user profile to the mcs_writer table.

Specified by:
create in interface LeadClientIntf
Parameters:
user - A MyLeadUser object.
Returns:
ReturnType - Values returned are:
ReturnType.OPERATION_SUCCESSFUL or
ReturnType.AUTHORIZATION_ERROR
Throws:
org.globus.mcs.client.MCSException - If an error occurs during execution of the request then this Exception is thrown.
See Also:
MyLeadUser, MCSException, ReturnType

update

public org.globus.mcs.common.ReturnType update(java.lang.String dn,
                                               MyLeadUser user)
                                        throws org.globus.mcs.client.MCSException
This method takes an instance of MyLeadUser which is used to update an existing myLEAD user profile in the mcs_writer table.

Specified by:
update in interface LeadClientIntf
Parameters:
dn - Distinguished name of user requesting the change.
user - A MyLeadUser object.
Returns:
ReturnType - Values returned are:
ReturnType.OPERATION_SUCCESSFUL or
ReturnType.AUTHORIZATION_ERROR
Throws:
org.globus.mcs.client.MCSException - If an error occurs during execution of the request then this Exception is thrown.
See Also:
MyLeadUser, MCSException, ReturnType

addAttribute

public org.globus.mcs.common.ReturnType addAttribute(java.lang.String dn,
                                                     MyLeadAttrData attribute,
                                                     java.lang.String parentName,
                                                     java.lang.String parentType)
                                              throws org.globus.mcs.client.MCSException
This method takes a MyLeadAttrData object and adds it to the object specified by the parent name passed as a parameter.

Specified by:
addAttribute in interface LeadClientIntf
Parameters:
dn - Distinguished name of the user adding the attribute.
attribute - A MyLeadAttrData object.
parentName - String with the unique name of the project, experiment, collection, or file the attribute is being added to.
parentType - String with the type of the parent - must match one of the types from mlAggregationType in the leadActivity schema.
Returns:
ReturnType - Values returned are: ReturnType.OPERATION_SUCCESSFUL or
ReturnType.AUTHORIZATION_ERROR
Throws:
org.globus.mcs.client.MCSException - If an error occurs during execution of the request then this Exception is thrown.
See Also:
MyLeadAttrData, MCSException, ReturnType

getWorkflowTemplates

public org.globus.mcs.common.ReturnType getWorkflowTemplates(java.lang.String dn,
                                                             java.lang.String invName,
                                                             LeadStringHolder results)
                                                      throws org.globus.mcs.client.MCSException
Deprecated. As of version 0.3 Alpha - instead use queryLead with the TARGET_ATTR filter.

This method returns all workflow templates associated with a given investigation.

Parameters:
dn - Distinguished name
invName - Name of the investigation
results - Holds all the workflow templates
Returns:
ReturnType - Values returned are ReturnType.OPERATION_SUCCESSFUL, ReturnType.NO_RESULTS_FOUND
Throws:
org.globus.mcs.client.MCSException - If any error occurs during execution of request this Exception is thrown.
See Also:
MCSException, ReturnType

getWorkflowInstances

public org.globus.mcs.common.ReturnType getWorkflowInstances(java.lang.String dn,
                                                             java.lang.String expName,
                                                             LeadStringHolder results)
                                                      throws org.globus.mcs.client.MCSException
Deprecated. As of version 0.3 Alpha - instead use queryLead with the TARGET_ATTR filter.

This method returns all workflow instances associated with a given experiment.

Parameters:
dn - Distinguished name
expName - Name of the experiment
results - Holds all the workflow instances
Returns:
ReturnType - Values returned are ReturnType.OPERATION_SUCCESSFUL, ReturnType.NO_RESULTS_FOUND
Throws:
org.globus.mcs.client.MCSException - If any error occurs during execution of request this Exception is thrown.
See Also:
MCSException, ReturnType

getNotifications

public org.globus.mcs.common.ReturnType getNotifications(java.lang.String dn,
                                                         java.lang.String expName,
                                                         LeadStringHolder results)
                                                  throws org.globus.mcs.client.MCSException
Deprecated. As of version 0.3 Alpha - instead use queryLead with the TARGET_ATTR filter.

This method returns notifications associated with a given experiment.

Parameters:
dn - Distinguished name
expName - Name of the experiment
results - Holds all the notifications
Returns:
ReturnType - Values returned are ReturnType.OPERATION_SUCCESSFUL, ReturnType.NO_RESULTS_FOUND
Throws:
org.globus.mcs.client.MCSException - If any error occurs during execution of request this Exception is thrown.
See Also:
MCSException, ReturnType

getServiceUrl

public java.lang.String getServiceUrl()
This method returns the endpoint url of the service that is currently being accessed. This method is the same as in MCSClient.

Specified by:
getServiceUrl in interface LeadClientIntf
Returns:
String

setAuthentication

public void setAuthentication(boolean authentic)
This method allows you to make an authenticated connection to the myLEAD service. This method is the same as in MCSClient.

Specified by:
setAuthentication in interface LeadClientIntf
Parameters:
authentic - if true the authentication is set and you will require a valid proxy to use the authentication. if false then authentication is removed.

isAuthenticated

public boolean isAuthenticated()
This method allows the user to find out whether this client is working in authenticated mode. This method is the same as in MCSClient.

Specified by:
isAuthenticated in interface LeadClientIntf
Returns:
boolean - Values returned are:
true - if the client is working in authenticated mode
false - if the client is working in non authenticated mode

close

public void close()
           throws org.globus.mcs.client.MCSException
Closes the grid service connection and destroys the service instance. This method is the same as in MCSClient.

Specified by:
close in interface LeadClientIntf
Throws:
org.globus.mcs.client.MCSException - If any error occurs during closing the service instance this Exception is thrown.
See Also:
MCSException

finalize

protected void finalize()