com.infoengine.SAK
Class IeService

java.lang.Object
  com.infoengine.SAK.IeService

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable

Direct Known Subclasses:

InfoEngine

public class IeService
extends java.lang.Object
implements java.lang.Cloneable, java.io.Serializable

Use the Server Access Kit (SAK) to access the Info*Engine Server programmatically.

The SAK, embodied in the IeService Object, is a Java object that provides access to the Info*Engine server. It executes Info*Engine templates and tasks. It allows the caller to obtain the raw output from these, and it also supports creation and management of an internal collection of Info*Engine group objects.

To use the SAK, you must instantiate an IeService object and then use the IeService object to initiate Info*Engine requests by supplying the URLs of templates and tasks. After initiating a request and providing optional parameter names and values, you can use the IeService object to obtain an input stream. From the input stream, you can read the result of the request, or if a task is initiated, you can request that the results of the task be added to an internally maintained collection of Info*Engine group objects. By using the IeService object methods that provide access to the internal collection, you can obtain groups, elements, and attributes from the collection.

See Also:

Serialized Form

Constructor Summary

IeService()
Create an instance that is not associated with any particular server.

IeService(java.lang.String serverUri)
Create an instance assocated with an Info*Engine server identified by the specified URI.

Method Summary

void	addAttributeValue(java.lang.String gName, int index, java.lang.String attName, java.lang.Object attValue) add an attribute value to a group
void	addGroup(Group group) Adds a group to the internal collection.
void	beginRequest(java.lang.String templatePath) Initiate a request to the Info*Engine server.
java.lang.Object	clone() Returns a shallow copy of the object.
Att	getAttribute(java.lang.String groupName, int index, java.lang.String attrName) Return a named attribute of an element selected by index.
Att	getAttribute(java.lang.String groupName, java.lang.String keyName, java.lang.String keyValue, java.lang.String attrName) Return a named attribute of an element selected by attribute name and value.
java.util.Enumeration	getAttributeNames(java.lang.String name, int index) Return the names of the attributes of an element of a group.
java.lang.String	getAttributeValue(java.lang.String groupName, int index, java.lang.String attrName) Return the value of a named attribute of an element selected by index.
java.lang.String	getAttributeValue(java.lang.String groupName, java.lang.String keyName, java.lang.String keyValue, java.lang.String attrName) Return the value of a named attribute of an element selected by attribute name and value.
java.util.Vector	getAttributeValues(java.lang.String groupName, int index, java.lang.String attrName) Return the values of a named attribute of an element selected by index.
java.util.Vector	getAttributeValues(java.lang.String groupName, java.lang.String keyName, java.lang.String keyValue, java.lang.String attrName) Return the values of a named attribute of an element selected by attribute name and value.
IeCollection	getCollection() Return the object that holds the internal collection of Info*Engine group objects.
java.util.Vector	getColumn(java.lang.String groupName, java.lang.String attrName) Return all of the values of a named attribute of all elements of a group.
java.lang.String	getContentType() Return the MIME content type associated with the server response.
int	getElementCount(java.lang.String name) Return the number of elements in a group.
java.util.Enumeration	getElements(java.lang.String name) Return the elements of a group as an Enumeration.
boolean	getEnableExceptions() Return an indication of whether exceptions will be thrown when returned from tasks have any groups that contain status values indicating failures.
Group	getGroup() Return a group from the internal collection, as an Info*Engine Group object.
Group	getGroup(java.lang.String name) Return a group from the internal collection, as an Info*Engine Group object.
java.util.Enumeration	getGroupNames() Return the names of the groups contained in the internal collection.
java.lang.String	getGroupXML(java.lang.String name) Return a group from the internal collection, as a String in Info*Engine format.
java.io.InputStream	getInputStream() Return an input stream containing the server's response to the request.
java.util.Locale	getLocale() Return the locale that is currently associated with this service object.
java.lang.String	getMessage(java.lang.String name) Return the message string associated with a group.
Content	getNextContent() Return the next MIME content object from the server response stream.
java.util.Vector	getRow(java.lang.String groupName, int index) Return all of the values of an element of a group.
int	getStatus(java.lang.String name) Return the status value associated with a group.
java.util.Map<java.lang.String,Group>	getVdbAsMap() Generates a snapshot of the current VDB as a java map where the key is the group name and the value is the group object.
void	removeAllGroups() Remove all groups from the collection.
void	removeGroup(java.lang.String name) Remove a group from the collection.
void	sendCollection() Send the internal collection to the server.
void	sendContent(java.lang.String contentType, java.lang.String name, java.lang.String filename, java.io.InputStream is) Send content of the request to the server.
void	sendGroup(java.lang.String name) Send a group from the internal collection to the server.
void	sendParameter(java.lang.String name, java.lang.String value) Send a parameter of the request to the server.
void	setAttributeValue(java.lang.String gName, int index, java.lang.String attName, java.lang.Object attValue) set an attribute value in a group
void	setCollection(IeCollection collection) Sets the object that holds the internal collection of Info*Engine group objects.
void	setCredentials(java.lang.String name, java.lang.String password) Establish the name and password of the user for which requests will be made.
void	setEnableExceptions(boolean enable) Enable or disable the throwing of exceptions when tasks return groups that contain status values indicating failures.
void	setLanguagePreferences(java.lang.String languagePreferences) Establish the language preferences that will be used by Info*Engine in selecting an appropriate locale for each request.
void	setLocale(java.util.Locale locale) Establish the locale that will be used in generating localized messages such as error messages.
void	setServerUri(java.lang.String serverUri) Establish the URI of the server to which requests will be sent.
java.lang.String	toString() Read all of the content objects returned in the server response and concatenate their String representations.
void	updateCollection() Get the next Content object from the server response stream and merge the Info*Engine group objects contained within it into the internal collection.
void	updateCollection(Content content) Merge the Info*Engine group objects contained within a Content object into the internal collection.
void	updateCollection(IeCollection collection) Merge the Info*Engine groups contained within a specified collection into the internal collection.
void	writeNextContent(java.io.OutputStream os) Write the next Content object to an output stream.
void	writeNextContent(java.io.Writer writer) Write the next Content object to a Writer.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

IeService

public IeService()

Create an instance that is not associated with any particular server. Use setServerUri to establish the URI of the server to which Info*Engine requests will be sent.

IeService

public IeService(java.lang.String serverUri)

Create an instance assocated with an Info*Engine server identified by the specified URI.

Parameters:

serverUri - the URI of the server with which this instance will be associated

Method Detail

setServerUri

public void setServerUri(java.lang.String serverUri)

Establish the URI of the server to which requests will be sent.

Parameters:

serverUri - the URI of the server to which requests will be sent

setCredentials

public void setCredentials(java.lang.String name,
                           java.lang.String password)

Establish the name and password of the user for which requests will be made.

Parameters:

name - the username of the user

password - the user's password

setLanguagePreferences

public void setLanguagePreferences(java.lang.String languagePreferences)

Establish the language preferences that will be used by Info*Engine in selecting an appropriate locale for each request.

Parameters:

languagePreferences - the language preferences, encoded as for an HTTP Accept-Language header

setLocale

public void setLocale(java.util.Locale locale)

Establish the locale that will be used in generating localized messages such as error messages.

Parameters:

locale - the locale to be used in generating localized messages

getLocale

public java.util.Locale getLocale()

Return the locale that is currently associated with this service object.

Returns:

The locale currently associated with this service object.

beginRequest

public void beginRequest(java.lang.String templatePath)
                  throws IeServiceException

Initiate a request to the Info*Engine server. The templatePath parameter is appended to the server URI (specified in the constructor or by calling setServerUri) to produce the full URI of the template or task to be executed. If a server URI has not been supplied via the constructor or setServerUri, the templatePath parameter is assumed to be a fully qualified template/task URI. If the template or task requires parameters, use sendParameters to send the parameters after executing this method and before obtaining the output stream or attempting to update the collection via updateCollection.

Parameters:

templatePath - the pathname of a template or task.

Throws:

IeServiceException - if the request was not initiated successfully

sendParameter

public void sendParameter(java.lang.String name,
                          java.lang.String value)
                   throws IeServiceException

Send a parameter of the request to the server. Use this method to send parameters required by a request. Before calling this method, call beginRequest to initiate the request.

Parameters:

name - the name of the parameter

value - the value of the parameter

Throws:

IeServiceException - if the parameter was not sent successfully

sendGroup

public void sendGroup(java.lang.String name)
               throws IeServiceException

Send a group from the internal collection to the server. This has the effect of initializing the VDB of the template or task to a non-empty set of groups (the group specified) before the template or task begins execution. If the template or task accepts content too, use sendCollection before using sendContent to send any content.

Parameters:

name - the name of the group to send

Throws:

IeServiceException - if the content was not sent successfully

sendCollection

public void sendCollection()
                    throws IeServiceException

Send the internal collection to the server. This has the effect of initializing the VDB of the template or task to a non-empty set of groups (all of the groups in the internal collection) before the template or task begins execution. If the template or task accepts content too, use sendCollection before using sendContent to send any content.

Throws:

IeServiceException - if the content was not sent successfully

sendContent

public void sendContent(java.lang.String contentType,
                        java.lang.String name,
                        java.lang.String filename,
                        java.io.InputStream is)
                 throws IeServiceException

Send content of the request to the server. This method sends the contents of an input stream as a bulk parameter to a template or task. If the template or task accepts both parameters and content, use sendParameter to send all parameters before using sendContent to send any content.

Parameters:

contentType - the MIME type of the content

name - the name of the content

filename - the file name, if any, associated with the content

is - the input stream containing the content

Throws:

IeServiceException - if the content was not sent successfully

getInputStream

public java.io.InputStream getInputStream()
                                   throws IeServiceException

Return an input stream containing the server's response to the request. Normally, the stream will contain HTML text if a template was executed, or XML text if a task was executed.

Returns:

The stream containing the server's response

Throws:

IeServiceException - if the input stream could not be obtained successfully, possibly because the request failed

getContentType

public java.lang.String getContentType()
                                throws IeServiceException

Return the MIME content type associated with the server response.

Returns:

The MIME content type of the server response

Throws:

IeServiceException - if the content type could not be obtained successfully, possibly because the request failed

getNextContent

public Content getNextContent()
                       throws IeServiceException

Return the next MIME content object from the server response stream. This object can then be queried for its MIME type, and an input stream can be obtained from it in order to read its contents.

Returns:

The next MIME content object, null if no more contents in server response stream

Throws:

IeServiceException - if the next content object was not obtained successfully, possibly because the request failed

writeNextContent

public void writeNextContent(java.io.OutputStream os)
                      throws IeServiceException

Write the next Content object to an output stream.

Parameters:

os - the output stream on which to write the content

Throws:

IeServiceException - if the next content object was not obtained successfully, or the output was not written successfully

writeNextContent

public void writeNextContent(java.io.Writer writer)
                      throws IeServiceException

Write the next Content object to a Writer.

Parameters:

writer - the Writer on which to write the content

Throws:

IeServiceException - if the next content object was not obtained successfully, or the output was not written successfully

setEnableExceptions

public void setEnableExceptions(boolean enable)

Enable or disable the throwing of exceptions when tasks return groups that contain status values indicating failures. The default behavior is that exceptions are not thrown when failure status is detected.

Parameters:

enable - true if the throwing of exceptions is to be enabled, false if the throwing of exception is to be disabled.

getEnableExceptions

public boolean getEnableExceptions()

Return an indication of whether exceptions will be thrown when returned from tasks have any groups that contain status values indicating failures.

Returns:

true if exceptions will be thrown when groups contain failure indications.

getVdbAsMap

public java.util.Map<java.lang.String,Group> getVdbAsMap()

Generates a snapshot of the current VDB as a java map where the key is the group name and the value is the group object.

Returns:

Map

getCollection

public IeCollection getCollection()

Return the object that holds the internal collection of Info*Engine group objects.

Returns:

The Info*Engine collection

setCollection

public void setCollection(IeCollection collection)

Sets the object that holds the internal collection of Info*Engine group objects.

Parameters:

collection - The Info*Engine collection

updateCollection

public void updateCollection()
                      throws IeServiceException

Get the next Content object from the server response stream and merge the Info*Engine group objects contained within it into the internal collection.

Throws:

IeServiceException - if the collection was not updated successfully, possibly because the request failed, so no XML objects were obtained from the server

updateCollection

public void updateCollection(Content content)
                      throws IeServiceException

Merge the Info*Engine group objects contained within a Content object into the internal collection.

Parameters:

content - the Content object to be merged

Throws:

IeServiceException - if the collection was not updated successfully, possibly because the Content object did not contain a valid set of Info*Engine groups

updateCollection

public void updateCollection(IeCollection collection)
                      throws IeServiceException

Merge the Info*Engine groups contained within a specified collection into the internal collection. This enables an application to maintain the internal collection across IeService object instances by using getCollection to obtain the internal collection and save it externally (for example, by storing it on a servlet session object), then using this method to merge the externally saved collection back into a new IeService instance later.

Parameters:

collection - the external collection to be merged into the internal collection

Throws:

IeServiceException - if the collection was not updated successfully, possibly because the request failed, so no XML objects were obtained from the server

getGroupNames

public java.util.Enumeration getGroupNames()

Return the names of the groups contained in the internal collection.

Returns:

The names of the groups in the collection

getGroup

public Group getGroup()

Return a group from the internal collection, as an Info*Engine Group object.

Parameters:

name - The name of the group to return. If null is specified, the last group in the collection is returned.

Returns:

The Info*Engine group, or null if the group is not found in the collection

getGroup

public Group getGroup(java.lang.String name)

Return a group from the internal collection, as an Info*Engine Group object.

Parameters:

name - The name of the group to return. If null is specified, the last group in the collection is returned.

Returns:

The Info*Engine group, or null if the group is not found in the collection

addGroup

public void addGroup(Group group)

Adds a group to the internal collection.

Parameters:

group - the Info*Engine group to add

getGroupXML

public java.lang.String getGroupXML(java.lang.String name)

Return a group from the internal collection, as a String in Info*Engine format.

Parameters:

name - the name of the group to return

Returns:

The XML representation of the group, or null if the group is not found in the collection

getElementCount

public int getElementCount(java.lang.String name)

Return the number of elements in a group.

Parameters:

name - the name of the group

Returns:

The number of elements contained in the group, or -1 if the group is not found in the internal collection

getElements

public java.util.Enumeration getElements(java.lang.String name)

Return the elements of a group as an Enumeration. Each element of the Enumeration is an Info*Engine object of class com.infoengine.object.factory.Element.

Parameters:

name - the name of the group

Returns:

The elements contained in the group

getAttributeNames

public java.util.Enumeration getAttributeNames(java.lang.String name,
                                               int index)

Return the names of the attributes of an element of a group.

Parameters:

name - the name of the group

index - the index of the element

Returns:

The names of the attributes of the element

getAttribute

public Att getAttribute(java.lang.String groupName,
                        int index,
                        java.lang.String attrName)

Return a named attribute of an element selected by index.

Parameters:

groupName - the name of the group from which to retrieve the attribute

index - the index of the element to select from the group

attrName - the name of the attribute to retrieve from the group

Returns:

The attribute, or null if the group is not found in the collection, or the element is not found in the group, or the attribute is not found in the element

getAttribute

public Att getAttribute(java.lang.String groupName,
                        java.lang.String keyName,
                        java.lang.String keyValue,
                        java.lang.String attrName)

Return a named attribute of an element selected by attribute name and value. The specified group is searched for an element that contains an attribute with a specified name and value (the key). If a matching element is found, the specified attribute of the element is returned.

Parameters:

groupName - the name of the group from which to retrieve the attribute

keyName - the name of the attribute used as a key to select an element from the group.

keyValue - the value of the attribute used as a key to select an element from the group

attrName - the name of the attribute to return from the selected element

Returns:

The attribute, or null if the group is not found in the collection, or the element is not found in the group, or the attribute is not found in the element

getAttributeValues

public java.util.Vector getAttributeValues(java.lang.String groupName,
                                           int index,
                                           java.lang.String attrName)

Return the values of a named attribute of an element selected by index.

Parameters:

groupName - the name of the group from which to retrieve the attribute values

index - the index of the element to select from the group

attrName - the name of the attribute from which to retrieve values

Returns:

The attribute values, or null if the group is not found in the collection, or the element is not found in the group, or the attribute is not found in the element

getAttributeValues

public java.util.Vector getAttributeValues(java.lang.String groupName,
                                           java.lang.String keyName,
                                           java.lang.String keyValue,
                                           java.lang.String attrName)

Return the values of a named attribute of an element selected by attribute name and value. The specified group is searched for an element that contains an attribute with a specified name and value (the key). If a matching element is found, the values of the specified attribute of the element are returned.

Parameters:

groupName - the name of the group from which to retrieve the attribute values

keyName - the name of the attribute used as a key to select an element from the group

keyValue - the value of the attribute used as a key to select an element from the group

attrName - the name of the attribute from which to retrieve values

Returns:

The attribute values, or null if the group is not found in the collection, or the element is not found in the group, or the attribute is not found in the element

getAttributeValue

public java.lang.String getAttributeValue(java.lang.String groupName,
                                          int index,
                                          java.lang.String attrName)

Return the value of a named attribute of an element selected by index. Use this method when you know that an attribute is single-valued. Otherwise, use getAttributeValues.

Parameters:

groupName - the name of the group from which to get the value

index - the index of the element to select from the group

attrName - the name of the attribute from which to retrieve a value

Returns:

The attribute value, or null if the group is not found in the collection, or the element is not found in the group, or the attribute is not found in the element

getAttributeValue

public java.lang.String getAttributeValue(java.lang.String groupName,
                                          java.lang.String keyName,
                                          java.lang.String keyValue,
                                          java.lang.String attrName)

Return the value of a named attribute of an element selected by attribute name and value. The specified group is searched for an element that contains an attribute with a specified name and value (the key). If a matching element is found, the value of the specified attribute of the element is returned. Use this method when you know that an attribute is single-valued. Otherwise, use getAttributeValues.

Parameters:

groupName - the name of the group from which to get the value

keyName - the name of the attribute used as a key to select an element from the group

keyValue - the value of the attribute used as a key to select an element from the group

attrName - the name of the attribute from which to retrieve a value

Returns:

The attribute value, or null if the group is not found in the collection, or the element is not found in the group, or the attribute is not found in the element

getRow

public java.util.Vector getRow(java.lang.String groupName,
                               int index)

Return all of the values of an element of a group.

Parameters:

groupName - the name of the group

index - the index of the element

Returns:

The attribute values, or null if the group is not found in the collection, or the element is not found in the group

getColumn

public java.util.Vector getColumn(java.lang.String groupName,
                                  java.lang.String attrName)

Return all of the values of a named attribute of all elements of a group.

Parameters:

groupName - the name of the group

attrName - the name of the attribute

Returns:

The attribute values, or null if the group is not found in the collection

getStatus

public int getStatus(java.lang.String name)

Return the status value associated with a group. A value of 0 indicates success. Any other value indicates failure.

Parameters:

name - the name of the group

Returns:

The status value, or -1 if the group is not found in the internal collection

getMessage

public java.lang.String getMessage(java.lang.String name)

Return the message string associated with a group.

Parameters:

name - the name of the group

Returns:

The message string, or null if the group is not found in the internal collection, or the group has no message string

removeGroup

public void removeGroup(java.lang.String name)

Remove a group from the collection.

Parameters:

name - the name of the group to remove

removeAllGroups

public void removeAllGroups()

Remove all groups from the collection.

toString

public java.lang.String toString()

Read all of the content objects returned in the server response and concatenate their String representations.

Overrides:

toString in class java.lang.Object

Returns:

A String representing the concatenation of the content objects returned by the server

clone

public final java.lang.Object clone()
                             throws java.lang.CloneNotSupportedException

Returns a shallow copy of the object.

Overrides:

clone in class java.lang.Object

Returns:

The shallow copy

Throws:

java.lang.CloneNotSupportedException

setAttributeValue

public void setAttributeValue(java.lang.String gName,
                              int index,
                              java.lang.String attName,
                              java.lang.Object attValue)

set an attribute value in a group

Parameters:

gName - - the name of the group

index - - the element index to add the attribute in

attName - - the name of the attribute to set

attValue - - the attribute value

addAttributeValue

public void addAttributeValue(java.lang.String gName,
                              int index,
                              java.lang.String attName,
                              java.lang.Object attValue)

add an attribute value to a group

Parameters:

gName - - the name of the group

index - - the element index to add the attribute in

attName - - the name of the attribute to set

attValue - - the attribute value