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. For publishing reports locally see LocalDocumentGenerator.


Constructor Summary
RemoteDocumentGenerator(Credential credential, java.lang.String jobURI)
          Constructs a new RemoteDocumentGenerator instance that connects to the given server.
RemoteDocumentGenerator(java.lang.String serverAddress, Credential credential)
          Constructs a new RemoteDocumentGenerator instance that connects to the given server.
 
Method Summary
 void addStatusListener(RPEListener listener)
          Deprecated. 
 java.lang.Thread connectToJob(java.lang.String job)
          Connects to an existing job.
 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 archive.
 void enableDebug(boolean debug)
          See IDocumentGenerator.enableDebug(boolean)
 java.lang.String getConfigurationPath(java.net.URI path)
          Deprecated. 
 java.lang.String getJobURI()
          Returns the URI of the job to which this generator is attached.
 java.net.URI getLog()
          Returns the URI of the server log file for the remote document generation process.
 java.lang.String getOwner()
          Returns the user name that started the remote document generator.
 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 used for the remote publishing process.
 com.ibm.rational.rpe.engine.RRDGEngine.EngineStatus getStatus()
          See IDocumentGenerator.getStatus()
 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 the given Document Specification and returns the thread that monitors the remote execution.
 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 in the calling thread.
 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)
          See IDocumentGenerator.registerListener(RPEListener)
 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)
          Internal
 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)
          See IDocumentGenerator.unregisterListener(RPEListener)
 
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)
Constructs a new RemoteDocumentGenerator instance that connects to the given server. This constructor is to be used for RemoteDocumentGenerator instances used to run new remote document generation jobs.

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]/rpews/"
credential - the Credential information to use when connecting to the service. Optional

RemoteDocumentGenerator

public RemoteDocumentGenerator(Credential credential,
                               java.lang.String jobURI)
Constructs a new RemoteDocumentGenerator instance that connects to the given server. This constructor is to be used for RemoteDocumentGenerator instances used to run new remote document generation jobs.

Parameters:
serverAddress - the URL of the job to connect to. Example: http://server[:port]/rpews/monitor/jobs/7c6dd6ac-5fa1-4a7b-91dd-be7209e256ee
credential - the Credential information to use when connecting to the service. Optional
Method Detail

getJobURI

public java.lang.String getJobURI()
Returns the URI of the job to which this generator is attached. This value is only valid after the document generation process has been successfully registered on the document generation server

Returns:

getLog

public java.net.URI getLog()
Returns the URI of the server log file for the remote document generation process.


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 then null is returned. As the value is always read from the server, for a faster processing the getLog() should be called first and if it returns null this method can then be used.

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 nocurrent job than null is returned

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

getConfigurationPath

@Deprecated
public java.lang.String getConfigurationPath(java.net.URI path)
Deprecated. 

Deprecated, not use.


enableDebug

public void enableDebug(boolean debug)
See IDocumentGenerator.enableDebug(boolean)

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 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 URI of the archive containing the result files

downloadResult

public java.lang.String downloadResult()
                                throws AuthenticationException,
                                       java.io.IOException
Downloads the results archive.

Returns:
Throws:
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 in the calling thread. As this can be a time consuming operation the publish(RPEDocumentSpecification) should be used when the calling thread is not to be blocked.

Status messages regarding the progress are passed to the registered listeners.

NOTE: 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. Once connected this RemoteDocumentGenerator instance will behave just like it would have just started the remote document generation

Parameters:
job - the URI of the job to connect to
Returns:
a thread where the job is executed. If the jobs was complete the thread finishes immediately
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. Once connected this RemoteDocumentGenerator instance will behave just like it would have just started the remote document generation

Parameters:
job - the URI of the job to connect to
Returns:
the execution result of the job
Throws:
RPEException

publish

public java.lang.Thread publish(RPEDocumentSpecification docSpec,
                                int previewQueryLimit)
                         throws RPEException
Starts the publishing process for the given Document Specification and returns the thread that monitors the remote execution. The thread finishes when the remote document generations is done. 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)
See IDocumentGenerator.registerListener(RPEListener)

Specified by:
registerListener in interface IDocumentGenerator

unregisterListener

public void unregisterListener(RPEListener listener)
See IDocumentGenerator.unregisterListener(RPEListener)

Specified by:
unregisterListener in interface IDocumentGenerator

getResultPage

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

Deprecated, do not use. This method always returns null.


addStatusListener

@Deprecated
public void addStatusListener(RPEListener listener)
Deprecated. 

Deprecated, use registerListener(com.ibm.rational.rpe.api.docspec.RPEListener)


removeStatusListener

@Deprecated
public void removeStatusListener(RPEListener listener)
Deprecated. 

Deprecated, use unregisterListener(com.ibm.rational.rpe.api.docspec.RPEListener)


publish

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

Deprecated, use publish(RPEDocumentSpecification, int)

Throws:
RPEException

publishSync

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

Deprecated, use publishSync(RPEDocumentSpecification, int)

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 ( RESULT_TYPE_ARCHIVE or RESULT_TYPE_LOG)

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

getStatus

public com.ibm.rational.rpe.engine.RRDGEngine.EngineStatus getStatus()
See IDocumentGenerator.getStatus()

Specified by:
getStatus in interface IDocumentGenerator
Returns:

getOwner

public java.lang.String getOwner()
Returns the user name that started the remote document generator.


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)
Internal