Overview  Package   Class  Tree  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.datamining.resource
Interface Connection

public interface Connection

A Connection instance serves the following purposes:

JDM named objects are enumerated in NamedObject.

The various get methods enable retrieval of named objects according to simple filtering specifications. Minimally, this inlcudes specifying a time window for when the object was created.

Due to the authentication and communication setup done when a Connection is created, a Connection is a relatively heavyweight JDM object. Typically a client application uses a single connection, but JDM does not restrict applications from using multiple Connection instances. However, each thread must use its own Connection instance.

Author:
JSR-73 Java Data Mining Expert Group

Method Summary
 void close()
          Closes the connection and releases resources associated with the Connection.
 boolean doesObjectExist(java.lang.String objectName, NamedObject objectType)
          Returns true if the object exists in the metadata repository associated with the connection.
 ExecutionHandle execute(java.lang.String taskName)
          Submits the task for asynchronous execution to the DME.
 ExecutionStatus execute(Task task, java.lang.Long timeout)
          Invokes the provided task synchronously.
 ConnectionSpec getConnectionSpec()
          Returns the connection specification used to create this connection if the getConnection(ConnectionSpec) method was used to create the connection.
 java.util.Date getCreationDate(java.lang.String objectName, NamedObject objectType)
          Returns the creation date of the specified named object.
 java.lang.String getDescription(java.lang.String objectName, NamedObject objectType)
          Returns the description of the specified mining object.
 ExecutionHandle[] getExecutionHandles(java.lang.String taskName)
          Returns all execution handles, running and completed, associated with the task.
 Factory getFactory(java.lang.String objectName)
          Returns a factory class for the specified object.
 ExecutionHandle getLastExecutionHandle(java.lang.String taskName)
          Returns the most recent execution handle associated with the task, whether its execution is still running or finished.
 java.lang.String[] getLoadedModels()
          Returns an array of model names that are currently loaded.
 java.util.Locale getLocale()
          Returns the locale of the connection.
 int getMaxDescriptionLength()
          Returns the maximum length in bytes for object descriptions.
 int getMaxNameLength()
          Returns the maximum string length for named objects in bytes.
 ConnectionMetaData getMetaData()
          Gets the information on the underlying DME instance represented through an active connection.
 NamedObject[] getNamedObjects(PersistenceOption persistenceOption)
          Returns an array of object types that are persisted in the specified way.
 java.util.Collection getObjectNames(NamedObject objectType)
          Returns a collection of the names of the objects of the specified type.
 MiningAlgorithm[] getSupportedAlgorithms(MiningFunction function)
          Returns an array of mining algorithms that are supported by the specified mining function.
 MiningFunction[] getSupportedFunctions()
          Returns an array of mining functions that are supported by the implementation.
 void removeObject(java.lang.String name, NamedObject objectType)
          Drops the named object in the metadata repository of the appropriate named object namespace.
 void renameObject(java.lang.String oldName, java.lang.String newName, NamedObject objectType)
          Renames the specified object in the metadata repository of the appropriate named object namespace.
 void requestModelLoad(java.lang.String modelName)
          Informs the DME that the named model may be used for scoring to enhance performance.
 void requestModelUnload(java.lang.String modelName)
          Informs the DME that the user is finished with the model and that the model may be removed from memory if necessary.
 java.util.Collection retrieveModelObjects(MiningFunction function, MiningAlgorithm algorithm, java.util.Date createdAfter, java.util.Date createdBefore)
          Returns a collection of Model objects for the specified function and algorithm that were created within the specified time interval (createAfter to createBefore).
 MiningObject retrieveObject(java.lang.String objectIdentifier)
          Retrieves a copy of the object specified by the identifier in the metadata repository associated with the connection.
 MiningObject retrieveObject(java.lang.String name, NamedObject objectType)
          Retrieves a copy of the named object in the metadata repository associated with the connection.
 java.util.Collection retrieveObjects(java.util.Date createdAfter, java.util.Date createdBefore, NamedObject objectType)
          Returns a collection of mining objects of the given type that were created within the specified time interval (from createAfter to createBefore).
 java.util.Collection retrieveObjects(java.util.Date createdAfter, java.util.Date createdBefore, NamedObject objectType, Enum minorType)
          Returns a collection of mining objects of the specified type that were created within the specified time interval (from createAfter to createBefore).
 void saveObject(java.lang.String name, MiningObject object, boolean replace)
          Saves the object in the metadata repository (associated with the connection) with the name provided.
 void setDescription(java.lang.String objectName, NamedObject objectType, java.lang.String description)
          Sets the description of the specified mining object.
 void setLocale(java.util.Locale locale)
          Sets the locale of the connection.
 boolean supportsCapability(MiningFunction function, MiningAlgorithm algorithm, MiningTask taskType)
          Returns true if the specified combination of mining capability is supported: If only function is provided: returns true if the specified function is supported.
 boolean supportsCapability(NamedObject object, PersistenceOption persistence)
          Returns true if the specified object type and persistence option is supported.
 

Method Detail

close

public void close()
           throws JDMException
Closes the connection and releases resources associated with the Connection. Further method invocations on a closed connection result in an exception.

Closing a connection will unload all currently loaded models.

Closing a connection invalidates any objects remaining at the client. Their behavior after connection close is undefined.

Returns:
void
Throws:
JDMException

doesObjectExist

public boolean doesObjectExist(java.lang.String objectName,
                               NamedObject objectType)
                        throws JDMException
Returns true if the object exists in the metadata repository associated with the connection. Returns false otherwise.

Parameters:
objectName - The name of the object under question.
objectType - The type of the object under question.
Returns:
boolean
Throws:
JDMException

execute

public ExecutionHandle execute(java.lang.String taskName)
                        throws JDMException
Submits the task for asynchronous execution to the DME. This method creates an ExecutionHandle associated with the task and returns it for subsequent status checking.

Parameters:
taskName - The name of the task to be executed.
Returns:
ExecutionHandle
Throws:
JDMException

execute

public ExecutionStatus execute(Task task,
                               java.lang.Long timeout)
                        throws JDMException
Invokes the provided task synchronously. This is typically to be used with single record scoring, but may be used in other contexts. If timeout is null, the method will block until completion, otherwise the method returns within the specified time. If task execution has not completed by the timeout, it is terminated. Upon completion, the method returns the final exectuion state.

Parameters:
task - The task to be executed.
timeout - The timeout value of the execution in seconds.
Returns:
ExecutionStatus
Throws:
JDMException

getConnectionSpec

public ConnectionSpec getConnectionSpec()
Returns the connection specification used to create this connection if the getConnection(ConnectionSpec) method was used to create the connection. Returns null otherwise.

Returns:
ConnectionSpec

getCreationDate

public java.util.Date getCreationDate(java.lang.String objectName,
                                      NamedObject objectType)
                               throws JDMException
Returns the creation date of the specified named object.

Parameters:
objectName -
objectType -
Returns:
Date
Throws:
JDMException

getDescription

public java.lang.String getDescription(java.lang.String objectName,
                                       NamedObject objectType)
                                throws JDMException
Returns the description of the specified mining object.

Parameters:
objectName - The name of the mining object.
objectType - The type of the mining object.
Returns:
String
Throws:
JDMException

getExecutionHandles

public ExecutionHandle[] getExecutionHandles(java.lang.String taskName)
                                      throws JDMException
Returns all execution handles, running and completed, associated with the task. Returns null if the task has not started executing.

Parameters:
taskName - The name of the task whose execution handles are to be returned.
Returns:
ExecutionHandle[]
Throws:
JDMException

getFactory

public Factory getFactory(java.lang.String objectName)
                   throws JDMException
Returns a factory class for the specified object. Throws an exception if objectName is not valid. Throws a runtime exception JDMUnsupportedFeatureException if the factory is not implemented.

The parameter objectName must be the name of the object to be created by this factory. For example:

LogicalDataFactory f = (LogicalDataFactory) getFactory ("javax.datamining.data.LogicalData");

Parameters:
objectName -
Returns:
Factory
Throws:
JDMException

getLastExecutionHandle

public ExecutionHandle getLastExecutionHandle(java.lang.String taskName)
                                       throws JDMException
Returns the most recent execution handle associated with the task, whether its execution is still running or finished. Returns null if the task has not started execution.

Parameters:
taskName - The name of the task whose last execution handle is to be returned.
Returns:
ExecutionHandle
Throws:
JDMException

getLoadedModels

public java.lang.String[] getLoadedModels()
                                   throws JDMException
Returns an array of model names that are currently loaded. The result is an empty array if model loading is not supported.

Returns:
String[]
Throws:
JDMException

getLocale

public java.util.Locale getLocale()
Returns the locale of the connection.

Returns:
Locale

getMaxDescriptionLength

public int getMaxDescriptionLength()
Returns the maximum length in bytes for object descriptions. If a description exceeds this length, an exception is thrown.

The maximum length of a description is at least 64 bytes.

Returns:
int

getMaxNameLength

public int getMaxNameLength()
Returns the maximum string length for named objects in bytes. If an object's name exceeds this length, an exception is thrown.

The maximum name length supported must be at least 8 bytes.

Returns:
int

getMetaData

public ConnectionMetaData getMetaData()
                               throws JDMException
Gets the information on the underlying DME instance represented through an active connection. Throws an exception if the connection is closed.

Returns:
ConnectionMetaData
Throws:
JDMException

getNamedObjects

public NamedObject[] getNamedObjects(PersistenceOption persistenceOption)
                              throws JDMException
Returns an array of object types that are persisted in the specified way.

Parameters:
persistenceOption - The persistence option by which the objects are persisted.
Returns:
NamedObject[]
Throws:
JDMException

getObjectNames

public java.util.Collection getObjectNames(NamedObject objectType)
                                    throws JDMException
Returns a collection of the names of the objects of the specified type.

Parameters:
objectType - The type of the objects whose names are to be returned.
Returns:
Collection
Throws:
JDMException

getSupportedAlgorithms

public MiningAlgorithm[] getSupportedAlgorithms(MiningFunction function)
                                         throws JDMException
Returns an array of mining algorithms that are supported by the specified mining function. Throws an exception if the function is not supported.

Parameters:
function - A mining function whose supporting mining algorithms are to be returned.
Returns:
MiningAlgorithm[]
Throws:
JDMException

getSupportedFunctions

public MiningFunction[] getSupportedFunctions()
                                       throws JDMException
Returns an array of mining functions that are supported by the implementation. Returns at least one function.

Returns:
MiningFunction[]
Throws:
JDMException

removeObject

public void removeObject(java.lang.String name,
                         NamedObject objectType)
                  throws JDMException
Drops the named object in the metadata repository of the appropriate named object namespace. If the object is not found, an exception is thrown.

Parameters:
name - The name of the object to be removed.
objectType - The type of the object to be removed.
Returns:
void
Throws:
JDMException

renameObject

public void renameObject(java.lang.String oldName,
                         java.lang.String newName,
                         NamedObject objectType)
                  throws JDMException
Renames the specified object in the metadata repository of the appropriate named object namespace. If the object is not found or the new name is not unique, an exception is thrown.

Parameters:
oldName - The name of the object to be renamed.
newName - The new name of the object.
objectType - The type of the object to be renamed.
Returns:
void
Throws:
JDMException

requestModelLoad

public void requestModelLoad(java.lang.String modelName)
                      throws JDMException
Informs the DME that the named model may be used for scoring to enhance performance. The intent is for the model to remain in memory until unloadModel is invoked with the same model name, or the connection terminates and there are no connections using the named model.

This may be a no-op if vendor need not load models into memory for scoring or does not support the capability. It is an idempotent operation if the model has not changed.

This method can be invoked on multiple models. If the specified model does not exist, an exception is thrown.

Parameters:
modelName - The name of the model to be loaded.
Returns:
void
Throws:
JDMException

requestModelUnload

public void requestModelUnload(java.lang.String modelName)
                        throws JDMException
Informs the DME that the user is finished with the model and that the model may be removed from memory if necessary.

This may be a no-op if vendor does not require loading model into memory for scoring. It is an idempotent operation.

If the requested model does not exist, an exception is thrown.

Parameters:
modelName - The name of the model to be unloaded.
Returns:
void
Throws:
JDMException

retrieveModelObjects

public java.util.Collection retrieveModelObjects(MiningFunction function,
                                                 MiningAlgorithm algorithm,
                                                 java.util.Date createdAfter,
                                                 java.util.Date createdBefore)
                                          throws JDMException
Returns a collection of Model objects for the specified function and algorithm that were created within the specified time interval (createAfter to createBefore). The models are ordered in a manner which the model with the earliest timestamp comes first.

If createdBefore is null, the present system time is used. If createdAfter is null, the starting time is open-ended. If both are null, all Model objects for the specified function and algorithm in the connection are returned.

Parameters:
function - The type of the mining function.
algorithm - The type of the mining algorithm.
createdAfter - The beginning of the time interval.
createdBefore - The end of the time interval.
Returns:
Collection
Throws:
JDMException

retrieveObject

public MiningObject retrieveObject(java.lang.String objectIdentifier)
                            throws JDMException
Retrieves a copy of the object specified by the identifier in the metadata repository associated with the connection. The object identifier is assigned to the object when it is stored.

This method returns a new object instance. When the method is invoked a second time with the same object identifier, a different object instance is created and returned, but with the same content and object identifier.

The returned object must be cast to a proper type.

Parameters:
objectIdentifier - The identifier of the object to be retrieved. The identifier can be obtained from getObjectIdentifier of any retrieved named object.
Returns:
MiningObject
Throws:
JDMException

retrieveObject

public MiningObject retrieveObject(java.lang.String name,
                                   NamedObject objectType)
                            throws JDMException
Retrieves a copy of the named object in the metadata repository associated with the connection.

This method returns a new object instance. When the method is invoked a second time with the same parameters, a different object instance is created and returned, but with the same content, unless the object has been changed.

Parameters:
name - The name of the mining object to be returned.
objectType - The type of the mining object.
Returns:
MiningObject
Throws:
JDMException

retrieveObjects

public java.util.Collection retrieveObjects(java.util.Date createdAfter,
                                            java.util.Date createdBefore,
                                            NamedObject objectType)
                                     throws JDMException
Returns a collection of mining objects of the given type that were created within the specified time interval (from createAfter to createBefore). The objects are orderedwhere the object with the earliest timestamp comes first.

If createdBefore is null, the present system time is used. If createdAfter is null, the starting time is open-ended. If both are null, all mining objects in the current connection are returned.

If objectType is null, all named objects created within the specified time window are returned.

Parameters:
createdAfter - The beginning of the time interval.
createdBefore - The ending of the time interval.
objectType - The type of the mining objects to be returned.
Returns:
Collection
Throws:
JDMException

retrieveObjects

public java.util.Collection retrieveObjects(java.util.Date createdAfter,
                                            java.util.Date createdBefore,
                                            NamedObject objectType,
                                            Enum minorType)
                                     throws JDMException
Returns a collection of mining objects of the specified type that were created within the specified time interval (from createAfter to createBefore). The objects are ordered in a manner which the object with the earliest timestamp comes first.

If createdBefore is <b>null, the present system time is used. If createdAfter is null, the starting time is open-ended. If both are null, all objects of the specified type are returned.

MinorType is applicable only for objectType Model (minorType is MiningFunction), BuildSettings (MiningFunction), Task (MiningTask), and ApplySettings (MiningFunction). If minorType is null, all objects of the specified type are returned.

Parameters:
createdAfter - The beginning of the time interval.
createdBefore - The end of the time interval.
objectType - The type of the named objects to be returned.
minorType - A finer filtering criterion for the type of the named objects. For task and result objects, MiningTask that was used to create the objects can be used. For model and function settings objects, MiningFunction that was used to create the objects can be used. Otherwise, this parameter is ignored.
Returns:
Collection
Throws:
JDMException

saveObject

public void saveObject(java.lang.String name,
                       MiningObject object,
                       boolean replace)
                throws JDMException
Saves the object in the metadata repository (associated with the connection) with the name provided.

If replace is true, the existing object, if any, is overwritten, in which case this method effectively performs remove and save. If false and an object of the same type with the specified name already exists, an exception is thrown.

Parameters:
name -
object -
replace -
Returns:
void
Throws:
JDMException

setDescription

public void setDescription(java.lang.String objectName,
                           NamedObject objectType,
                           java.lang.String description)
                    throws JDMException
Sets the description of the specified mining object.

Parameters:
objectName - The name of the mining object.
objectType - The type of the mining object.
description - The description to be set.
Returns:
void
Throws:
JDMException

setLocale

public void setLocale(java.util.Locale locale)
               throws JDMException
Sets the locale of the connection. This locale is to be used to convert locale specific information presented from the server.

Parameters:
locale -
Returns:
void
Throws:
JDMException

supportsCapability

public boolean supportsCapability(MiningFunction function,
                                  MiningAlgorithm algorithm,
                                  MiningTask taskType)
                           throws JDMException
Returns true if the specified combination of mining capability is supported:

Returns false if a given combination is not supported.

Parameters:
function - The function to support the specified capabiliy.
algorithm - The algorithm to support the specified capability.
taskType - The type of task supported.
Returns:
boolean
Throws:
JDMException

supportsCapability

public boolean supportsCapability(NamedObject object,
                                  PersistenceOption persistence)
                           throws JDMException
Returns true if the specified object type and persistence option is supported. Returns false otherwise.

Parameters:
object - The type of the object.
persistence - The persistence option.
Returns:
boolean
Throws:
JDMException
Overview  Package   Class  Tree  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD