com.ibm.rational.rpe.api.docgen
Class RemoteDocumentGenerator

java.lang.Object
  extended by com.ibm.rational.rpe.api.docgen.RemoteDocumentGenerator
All Implemented Interfaces:
IDocumentGenerator, IControl

public class RemoteDocumentGenerator
extends java.lang.Object
implements IDocumentGenerator

Utility class for running reports using a remote web service instance, also for other operations available. For publishing reports using a local instance, see LocalDocumentGenerator.


Constructor Summary
RemoteDocumentGenerator(Credential credential, java.lang.String jobURI)
           
RemoteDocumentGenerator(java.lang.String serverAddress, Credential credential)
          Constructor for class RemoteDocumentGenerator
 
Method Summary
 void addStatusListener(RPEListener listener)
          Deprecated. 
 java.lang.Thread connectToJob(java.lang.String job)
          Connects to an existing job and returns a thread like the publish method does
 com.ibm.rational.rpe.engine.RRDGEngine.EngineStatus connectToJobSynch(java.lang.String job)
          Connects to an existing job and waits until the job is completed.
 java.lang.String downloadResult()
          Downloads the results using the credentials provided in the constructor
 void enableDebug(boolean debug)
          Enables the core debug mode for the document generation
 java.lang.String getConfigurationPath(java.net.URI path)
          Retrieves the path to the configuration file that needs to be passed to DocumentSpecificationBuilder methods.
 java.lang.String getJobURI()
           
 java.net.URI getLog()
           
 java.lang.String getOwner()
           
 java.net.URI getResultArchive()
          This method provides a URI to an archive containing all the output files requested in the Document Specification, once a publishing process has ended successfully.
 java.net.URL getResultPage()
          Deprecated. 
 java.util.List<RPEResult> getResults()
          Retrieves the results of a publishing process.
 java.lang.String getScheduleUrl()
          Specifies the schedule url if the job being executed was triggered through the report scheduler
 java.lang.String getServerAddress()
          Retrieves the server address currently used for the remote publishing process.
 com.ibm.rational.rpe.engine.RRDGEngine.EngineStatus getStatus()
          Returns the status of the generation
 void pause()
          'Pause' functionality is not implemented for RemoteDocumentGenerator
 java.lang.Thread publish(RPEDocumentSpecification docSpec)
          Deprecated. 
 java.lang.Thread publish(RPEDocumentSpecification docSpec, int previewQueryLimit)
          Starts the publishing process for a given Document Specification.
 void publishSync(RPEDocumentSpecification docSpec)
          Deprecated. 
 com.ibm.rational.rpe.engine.RRDGEngine.EngineStatus publishSync(RPEDocumentSpecification docSpec, int previewQueryLimit)
          Starts the publishing process for a given Document Specification.
 java.net.URI readJobLogURI()
          Reads the log URI for the current job from the server.
 java.net.URI readJobResultsURI()
          Reads the log results URI for the current job from the server.
 java.lang.String readJobStatus()
          Reads the status for the current job from the server.
 void registerListener(RPEListener listener)
          Registers a RPE listener for receiving important progress messages from the document generation
 void removeStatusListener(RPEListener listener)
          Deprecated. 
 void resume()
          'Resume' functionality is not implemented for RemoteDocumentGenerator
 void setOwner(java.lang.String owner)
          Specifies the actual user on behalf of whom the docgen is executed.
 void setScheduleUrl(java.lang.String scheduleUrl)
           
 void setServerAddress(java.lang.String serverAddress)
          Sets the server address to use for the remote publishing process.
 void stop()
          Stops a running publishing process.
 void unregisterListener(RPEListener listener)
          Unregisters the listener from the engine
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

RemoteDocumentGenerator

public RemoteDocumentGenerator(java.lang.String serverAddress,
                               Credential credential)
Constructor for class RemoteDocumentGenerator

Parameters:
serverAddress - a String containing a URL to the web service resource. Provide the full path to the web service description, for example: "http://server[:port]/rpe/services/RPEService?wsdl"

RemoteDocumentGenerator

public RemoteDocumentGenerator(Credential credential,
                               java.lang.String jobURI)
Method Detail

getJobURI

public java.lang.String getJobURI()

getLog

public java.net.URI getLog()

readJobLogURI

public java.net.URI readJobLogURI()
                           throws RPEException,
                                  java.net.URISyntaxException
Reads the log URI for the current job from the server. If there is no current job than null is returned getLog should be invoked first instead of this one to retrieved the URI cached locally

Returns:
the URI of the log or null.
Throws:
RPEException
java.net.URISyntaxException

readJobResultsURI

public java.net.URI readJobResultsURI()
                               throws RPEException,
                                      java.net.URISyntaxException
Reads the log results URI for the current job from the server. If there is no current job than null is returned

Returns:
the URI of the log or null.
Throws:
RPEException
java.net.URISyntaxException

readJobStatus

public java.lang.String readJobStatus()
                               throws RPEException
Reads the status for the current job from the server. If there is no current job than null is returned

Returns:
the URI of the log or null.
Throws:
RPEException
java.net.URISyntaxException

getConfigurationPath

public java.lang.String getConfigurationPath(java.net.URI path)
Retrieves the path to the configuration file that needs to be passed to DocumentSpecificationBuilder methods.

Parameters:
path - an URI consisting of a path to the configuration folder. If this parameter is null, this method returns a path computed based on the "RPE_HOME" system environment variable.
Returns:
the path to the appropriate configuration file, depending on the input parameter. If the return value is null, it means that both the "RPE_HOME" variable and the input parameter are not set correctly.

enableDebug

public void enableDebug(boolean debug)
Description copied from interface: IDocumentGenerator
Enables the core debug mode for the document generation

Specified by:
enableDebug in interface IDocumentGenerator

setServerAddress

public void setServerAddress(java.lang.String serverAddress)
Sets the server address to use for the remote publishing process.

Parameters:
serverAddress - a String containing a URL to the web service resource. Provide the full path to the web service description, for example: "http://server[:port]/rpe/services/RPEService?wsdl"

getServerAddress

public java.lang.String getServerAddress()
Retrieves the server address currently used for the remote publishing process.

Returns:
the currently set server address

pause

public void pause()
'Pause' functionality is not implemented for RemoteDocumentGenerator

Specified by:
pause in interface IControl

resume

public void resume()
'Resume' functionality is not implemented for RemoteDocumentGenerator

Specified by:
resume in interface IControl

stop

public void stop()
Stops a running publishing process.

Specified by:
stop in interface IControl

getResultArchive

public java.net.URI getResultArchive()
This method provides a URI to an archive containing all the output files requested in the Document Specification, once a publishing process has ended successfully.

Returns:
the archive containing the result files

downloadResult

public java.lang.String downloadResult()
                                throws com.ibm.rational.rpe.common.auth.AuthenticationException,
                                       java.io.IOException
Downloads the results using the credentials provided in the constructor

Returns:
Throws:
com.ibm.rational.rpe.common.auth.AuthenticationException
java.io.IOException

publishSync

public com.ibm.rational.rpe.engine.RRDGEngine.EngineStatus publishSync(RPEDocumentSpecification docSpec,
                                                                       int previewQueryLimit)
                                                                throws RPEException
Starts the publishing process for a given Document Specification. This can be a time consuming operation. Status messages regarding the progress are passed to the registered listeners.

This method does not return until the publishing thread has ended its execution.

Specified by:
publishSync in interface IDocumentGenerator
Parameters:
docSpec - the Document Specification to be published
Returns:
Throws:
RPEException

connectToJob

public java.lang.Thread connectToJob(java.lang.String job)
                              throws RPEException
Connects to an existing job and returns a thread like the publish method does

Parameters:
job -
Returns:
Throws:
RPEException

connectToJobSynch

public com.ibm.rational.rpe.engine.RRDGEngine.EngineStatus connectToJobSynch(java.lang.String job)
                                                                      throws RPEException
Connects to an existing job and waits until the job is completed. Similar to publishSync.

Parameters:
job -
Returns:
Throws:
RPEException

publish

public java.lang.Thread publish(RPEDocumentSpecification docSpec,
                                int previewQueryLimit)
                         throws RPEException
Starts the publishing process for a given Document Specification. This can be a time consuming operation. Status messages regarding the progress are passed to the registered listeners.

This method returns immediately after it has been called. The returning Thread object can be used to determine when the publish process has ended.

Specified by:
publish in interface IDocumentGenerator
Parameters:
docSpec - the Document Specification to be published
Returns:
the publishing execution Thread
Throws:
RPEException

registerListener

public void registerListener(RPEListener listener)
Description copied from interface: IDocumentGenerator
Registers a RPE listener for receiving important progress messages from the document generation

Specified by:
registerListener in interface IDocumentGenerator

unregisterListener

public void unregisterListener(RPEListener listener)
Description copied from interface: IDocumentGenerator
Unregisters the listener from the engine

Specified by:
unregisterListener in interface IDocumentGenerator

getResultPage

@Deprecated
public java.net.URL getResultPage()
Deprecated. 

This method provides a URL to a HTML page that presents a link to the result archive file, once a publishing process has ended successfully.

Returns:
the resource containing the result page

addStatusListener

@Deprecated
public void addStatusListener(RPEListener listener)
Deprecated. 

Deprecated, use registerListener


removeStatusListener

@Deprecated
public void removeStatusListener(RPEListener listener)
Deprecated. 

Deprecated, use unregisterListener


publish

@Deprecated
public java.lang.Thread publish(RPEDocumentSpecification docSpec)
                         throws RPEException
Deprecated. 

Deprecated, use publish(RPEDocumentSpecification docSpec, int previewLimit)

Throws:
RPEException

publishSync

@Deprecated
public void publishSync(RPEDocumentSpecification docSpec)
                 throws RPEException
Deprecated. 

Deprecated, use publishSync(RPEDocumentSpecification docSpec, int previewLimit)

Throws:
RPEException

getResults

public java.util.List<RPEResult> getResults()
Retrieves the results of a publishing process. Only 2 results are returned, one for the archive and the other for the log. The result objects have two properties: - the path - the type ( log or archive)

Specified by:
getResults in interface IDocumentGenerator
Returns:
the list of RPEResult objects

getStatus

public com.ibm.rational.rpe.engine.RRDGEngine.EngineStatus getStatus()
Description copied from interface: IDocumentGenerator
Returns the status of the generation

Specified by:
getStatus in interface IDocumentGenerator
Returns:

getOwner

public java.lang.String getOwner()

setOwner

public void setOwner(java.lang.String owner)
Specifies the actual user on behalf of whom the docgen is executed. Ignored by the server if the authenticated user (the one in credential) is not a MC Admin

Parameters:
owner -

getScheduleUrl

public java.lang.String getScheduleUrl()
Specifies the schedule url if the job being executed was triggered through the report scheduler

Parameters:
owner -

setScheduleUrl

public void setScheduleUrl(java.lang.String scheduleUrl)