com.autonomy.aci.services
Interface AgentFunctionality

public interface AgentFunctionality

Method Summary

Agent	copyAgent(Agent agent, User userNewOwner, java.lang.String sNewAgentname) Copy an agent from one user to another.
AciResponse	createAgent(Agent agent) Create the given agent on IDOL.
AciResponse	deleteAgent(Agent agent) Remove the given agent from IDOL.
Agent	getAgent(java.lang.String sAgentID) Reads the details of a user agent from IDOL.
Agent	getAgent(java.lang.String sAgentname, java.lang.String sUsername) Reads the details of a user agent from IDOL.
java.util.ArrayList	getAgentList(User user) Reads all of a user's agents from IDOL.
java.util.ArrayList	getAgentNames(User user) Reads the names of all of a user's agents from IDOL.
ResultList	getAgentResults(Agent agent, java.util.ArrayList alAgentGetResultsParams) Retrieve the documents that currently match an agent's training.
AciResponse	retrainAgent(Agent agent, java.util.ArrayList positiveDocs) Retrain the given agent on IDOL.
Agent	shareAgent(Agent agent, User userNewOwner, java.lang.String sNewAgentname) NOT CURRENTLY IMPLEMENTED.
AciResponse	updateAgent(Agent agent) Edit the given agent on IDOL.

Method Detail

createAgent

public AciResponse createAgent(Agent agent)
                        throws AciException,
                               AgentExistsException,
                               UserNotFoundException,
                               MaximumAgentsException

Create the given agent on IDOL.

Parameters:

agent - the agent to create. The agent must be populated with at least an agentname, a username or user ID and some training text or training documents.

Returns:

the response from IDOL to the agent creation request.

Throws:

AciException - if there was an error when making the request.

AgentExistsException - if the user already owns an agent with this name.

UserNotFoundException - if the user does not exist on IDOL.

MaximumAgentsException - if the user already has the maximum number allowed by the IDOL configuration.

deleteAgent

public AciResponse deleteAgent(Agent agent)
                        throws AciException,
                               AgentNotFoundException,
                               UserNotFoundException

Remove the given agent from IDOL.

Parameters:

agent - the agent to remove. The agent must be populated with at least an agentname and an username or user ID.

Returns:

the response from IDOL to the agent removal request.

Throws:

AciException - if there was an error when making the request.

AgentNotFoundException - if the user does not own an agent with this name.

UserNotFoundException - if the user does not exist on IDOL.

updateAgent

public AciResponse updateAgent(Agent agent)
                        throws AciException,
                               AgentNotFoundException,
                               UserNotFoundException

Edit the given agent on IDOL.

Parameters:

agent - the agent to create. The agent must be populated with at least an agentname, a username or user ID and some training text or training documents.

Returns:

the response from IDOL to the agent edit request.

Throws:

AciException - if there was an error when making the request.

AgentNotFoundException - if the user does not own an agent with this name.

UserNotFoundException - if the user does not exist on IDOL.

retrainAgent

public AciResponse retrainAgent(Agent agent,
                                java.util.ArrayList positiveDocs)
                         throws AciException,
                                AgentNotFoundException,
                                UserNotFoundException

Retrain the given agent on IDOL.

Parameters:

agent - the agent to create. The agent must be populated with at least an agentname, a username or user ID and some training text or training documents.

positiveDocs - list of retraining documents. The ArrayList must be contain a list of Document objects.

Returns:

the response from IDOL to the agent retrain request.

Throws:

AciException - if there was an error when making the request.

AgentNotFoundException - if the user does not own an agent with this name.

UserNotFoundException - if the user does not exist on IDOL.

getAgentList

public java.util.ArrayList getAgentList(User user)
                                 throws AciException,
                                        UserNotFoundException

Reads all of a user's agents from IDOL.

Parameters:

user - the user whose agents are required.

Returns:

an ArrayList of Agent objects representing all the agents the user has stored on IDOL.

Throws:

AciException - if there was an error when making the request.

UserNotFoundException - if the user does not exist on IDOL.

getAgentNames

public java.util.ArrayList getAgentNames(User user)
                                  throws AciException,
                                         UserNotFoundException

Reads the names of all of a user's agents from IDOL.

Parameters:

user - the user whose agents' names are required (must be populated at least with a username or user ID).

Returns:

an ArrayList of Strings giving the names of all the agents the user has stored on IDOL.

Throws:

AciException - if there was an error when making the request.

UserNotFoundException - if the user does not exist on IDOL.

getAgent

public Agent getAgent(java.lang.String sAgentname,
                      java.lang.String sUsername)
               throws AciException,
                      AgentNotFoundException,
                      UserNotFoundException

Reads the details of a user agent from IDOL.

Parameters:

sAgentname - the name of the agent whose details are required.

sUsername - the username of the user whose agent details are required.

Returns:

an Agent object representing the required agent.

Throws:

AciException - if there was an error when making the request.

AgentNotFoundException - if the specified agent does not exist on IDOL.

UserNotFoundException - if the specified user does not exist on IDOL.

getAgent

public Agent getAgent(java.lang.String sAgentID)
               throws AciException,
                      AgentNotFoundException,
                      UserNotFoundException

Reads the details of a user agent from IDOL.

Parameters:

sAgentID - the unique ID of the agent whose details are required.

Returns:

an Agent object representing the required agent.

Throws:

AciException - if there was an error when making the request.

AgentNotFoundException - if the specified agent does not exist on IDOL.

UserNotFoundException - if the specified user does not exist on IDOL.

copyAgent

public Agent copyAgent(Agent agent,
                       User userNewOwner,
                       java.lang.String sNewAgentname)
                throws AciException,
                       AgentNotFoundException,
                       UserNotFoundException,
                       MaximumAgentsException

Copy an agent from one user to another.

Parameters:

agent - the agent to be copied.

userNewOwner - the user who will own the new agent.

sNewAgentname - the name to give to the agent copy.

Returns:

the copied agent.

Throws:

AciException - if there was an error when making the request.

AgentNotFoundException - if the agent to be copied does not exist

UserNotFoundException - if the destination user does not exist on IDOL.

MaximumAgentsException - if the user already has the maximum number allowed by the IDOL configuration.

shareAgent

public Agent shareAgent(Agent agent,
                        User userNewOwner,
                        java.lang.String sNewAgentname)
                 throws AciException,
                        AgentNotFoundException,
                        UserNotFoundException,
                        AgentExistsException

NOT CURRENTLY IMPLEMENTED. Share a user's agent with another user.

Parameters:

agent - the agent to be shared.

userNewOwner - the user who will own the shared agent.

sNewAgentname - the name to give to the shared agent.

Returns:

an Agent object representing the shared agent.

Throws:

AciException - if there was an error when making the request.

AgentNotFoundException - if the specified agent does not exist on IDOL.

AgentExistsException - if the user already has an agent with the given name.

UserNotFoundException - if the specified user does not exist on IDOL.

getAgentResults

public ResultList getAgentResults(Agent agent,
                                  java.util.ArrayList alAgentGetResultsParams)
                           throws AciException,
                                  AgentNotFoundException,
                                  UserNotFoundException,
                                  DataStoreNotFoundException

Retrieve the documents that currently match an agent's training.

Parameters:

agent - the agent whose results are required.

alAgentGetResultsParams - extra parameters to send when retrieving agent results. Parameters set here will override any parameters set by the agent. Can be null.

Returns:

a ResultList containing the documents matching the agent's training.

Throws:

AciException - if there was an error when making the request.

AgentNotFoundException - if the specified agent does not exist on IDOL.

UserNotFoundException - if the specified user does not exist on IDOL.

DataStoreNotFoundException - if content was not available to retrieve results from.