org.soaplab.services
Class Reporter

java.lang.Object
  org.soaplab.services.Reporter

public class Reporter
extends java.lang.Object

An instance of a Reporter accompanies each "job" (an analysis invocation). It keeps the job status, it adapts job results (and passes them to a persistent manager to store them), etc.

Version:

$Id: Reporter.java,v 1.31 2011/05/13 10:14:45 marsenger Exp $

Author:

Martin Senger

Constructor Summary

Reporter(MetadataAccessor metadataAccessor, PersistentStorage percy, EventManager eman)
The main constructor.

Method Summary

void	cleanReport() Clean-up all so far reported messages.
void	error(java.lang.String msg) Add an error message to the 'report' result.
java.util.Properties	getJobProperties()
java.util.Map<java.lang.String,java.lang.Object>	getResults() Retrieve and return all available results, set so far.
java.util.Map<java.lang.String,java.lang.Object>	getResults(java.lang.String[] nameList)
java.util.Map<java.lang.String,java.lang.String>[]	getResultsInfo()
org.soaplab.services.JobState	getState() Return a container with job status.
void	report(java.lang.String msg) Add a message to the 'report' result.
void	report(java.lang.String msgName, java.io.File msgFile) Add a contents of the given file to the 'report' result.
void	report(java.lang.String msgName, java.lang.String msg) Add a property to the 'report' result.
void	sendEvent(AnalysisEvent event) Send an event to all event listeners.
void	setDetailedStatusResult() Store 'detailed_status' result persistently.
void	setJob(Job job) Remember what job this reporter is serving.
void	setJobProperties(java.util.Properties props)
void	setReportResult() Store 'report' result persistently.
void	setResult(java.lang.String resultName, java.lang.Object result) It stores given result under given name.
void	setState(org.soaplab.services.JobState state) Set the whole job state.

Methods inherited from class java.lang.Object

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

Constructor Detail

Reporter

public Reporter(MetadataAccessor metadataAccessor,
                PersistentStorage percy,
                EventManager eman)

The main constructor.

Parameters:

metadataAccessor - gives access to all service metadata; for example, it is used to find names of result adapters; in rare cases it can be null (when this reporter reports on a semi-functional job that was retrieved from the persistent storage, for example)

percy - manages all persistent storage handlers; used to store results; it cannot be null

eman - manages broadcasting events (about the status of the job) to all event listeners; it cannot be null

Method Detail

setJob

public void setJob(Job job)

Remember what job this reporter is serving. Should be call just once, and usually from a constructor of the Job.

Note that this method is here only because we have a chicken-egg problem: a job needs to know its reporter, and the reporter needs to know its job. Is there perhaps any established pattern to deal with such situations better?

setState

public void setState(org.soaplab.services.JobState state)

Set the whole job state. This is rarely used - because the reporter always creates a job state in its constructor, anyway. The method is here for specialized implementation of a Job that wishes to use its own state (a subclass of a regular JobState). It is also used when a semi-functional job (a job that was re-created from a persistent storage) is created long after it had finished.

Usually, for changing status of a job, use rather:

   reporter.getState().set (...);

.

getState

public org.soaplab.services.JobState getState()

Return a container with job status.

sendEvent

public void sendEvent(AnalysisEvent event)

Send an event to all event listeners.

cleanReport

public void cleanReport()

Clean-up all so far reported messages.

I wonder if we really need this method... (because the report will go away when its Reporter instance is garbage collected, anyway).

report

public void report(java.lang.String msg)

Add a message to the 'report' result. No newlines are automatically added.

error

public void error(java.lang.String msg)

Add an error message to the 'report' result. No newlines are automatically added.

Adding an error also influences what the 'summary report' will contain.

report

public void report(java.lang.String msgName,
                   java.lang.String msg)

Add a property to the 'report' result. It will be listed in the 'report' in the same order as added by this method. An already existing property will be extended by the new 'msg'.

Parameters:

msgName - names the property (will be used as a label in the report)

msg - message to be reported

report

public void report(java.lang.String msgName,
                   java.io.File msgFile)

Add a contents of the given file to the 'report' result. It will be listed at the end the 'report' in the same order as added by this method, under the given label.

Parameters:

msgName - names the property (will be used as a label in the report, unless it is empty)

msgFile - file containing reported message (TBD: when is this file read?)

setReportResult

public void setReportResult()
                     throws SoaplabException

Store 'report' result persistently. But keep it still in the memory so it can be updated.

Throws:

SoaplabException

setDetailedStatusResult

public void setDetailedStatusResult()
                             throws SoaplabException

Store 'detailed_status' result persistently.

Throws:

SoaplabException

setResult

public void setResult(java.lang.String resultName,
                      java.lang.Object result)
               throws SoaplabException

It stores given result under given name. For specialized output (report and detailed status), use specialized methods.

Before storing the result, it looks if there is an adaptor to convert the result. If so, it is called and the adapted result is put into a local temporary file. If there is no adaptor, it processes the result in the following way:

• If it is an input stream, it reads it and puts it into a local temporary file,
• If it is already a file, it makes its copy into a local temporary file,
• If it is a URL, it fetches its contents into a local file,
• If it is a string, it keeps it as it is.

The result is now either in a local file, or in memory. In any case, it is now passed to the persistence manager (which passes it further to all storage handlers).

TBD: A, yet not fully solved, question is what to do with these local temporary files? When to get rid of them? Note that we cannot remove files immediately, because the persistence manager call may return before the files are fully consumed). So, definitely, make them disappear when this application exits. But it can be alive for a long time. Other potential options are: (a) start a thread removing too old temporary files, or (b) change the persistent storage API so it can call me back when files are consumed, or (c) keep them and let some external, administrative tool to get rid of them time to time.

Result as a URL Then, it checks if this output can be also accessible as a URL. If it is the case - and if it can find enough properties to do so, it creates another output (derived from the 'resultName' by adding a "_url" suffix).

Throws:

SoaplabException

getResults

public java.util.Map<java.lang.String,java.lang.Object> getResults()
                                                            throws SoaplabException

Retrieve and return all available results, set so far.

Throws:

SoaplabException

getResults

public java.util.Map<java.lang.String,java.lang.Object> getResults(java.lang.String[] nameList)
                                                            throws SoaplabException

Throws:

SoaplabException

getResultsInfo

public java.util.Map<java.lang.String,java.lang.String>[] getResultsInfo()
                                                                  throws SoaplabException

Throws:

SoaplabException

getJobProperties

public java.util.Properties getJobProperties()
                                      throws SoaplabException

Throws:

SoaplabException

setJobProperties

public void setJobProperties(java.util.Properties props)
                      throws SoaplabException

Throws:

SoaplabException