com.ibm.rational.rpe.api.docspec
Class DocumentSpecificationBuilder

java.lang.Object
  extended by com.ibm.rational.rpe.api.docspec.DocumentSpecificationBuilder

public class DocumentSpecificationBuilder
extends java.lang.Object

Utility class for constructing and altering document specifications and document templates.


Field Summary
static java.lang.String DSX_EXTENSION
          The default extension used by RPE document specifications
 
Constructor Summary
DocumentSpecificationBuilder()
           
 
Method Summary
 RPEOutput addOutput(RPEDocumentSpecification docspec, java.lang.String type, java.lang.String driver)
          Adds the specified output type to the document specification.
 RPEDocumentSpecification create(java.lang.String configFile)
          Creates an empty document specification.
 RPEDocumentSpecification create(java.lang.String configFile, java.util.List<java.lang.String> templatesFile)
          Creates a new document specification from a list of document templates.
 RPETemplate createRuntimeTemplate(java.lang.String configFile, com.ibm.rational.rpe.common.template.model.Template template, java.lang.String path, Credential credential)
          Creates and returns a RPETemplate object from the given arguments.
 Feature getConfigurationForDatasource(java.lang.String configPath, java.lang.String type)
          Builds the configuration feature for the given data source type.
 com.ibm.rational.rpe.common.utils.IURIResolver getURIResolver()
          Returns the IURIResolver used by this DocumentSpecificationBuilder instance.
 com.ibm.rational.rpe.api.docspec.RPEConfiguration load(java.lang.String configPath)
          Loads a configuration file.
 RPEDocumentSpecification load(java.lang.String configPath, java.lang.String docSpecPath)
          Loads a document specification from the specified path.
 RPEDocumentSpecification load(java.lang.String configPath, java.lang.String docSpecPath, boolean strict)
          Loads a document specification from the specified path.
 RPEDocumentSpecification load(java.lang.String configPath, java.lang.String docSpecPath, java.lang.String srcDocSpecPath, boolean strict)
          Loads a document specification from the specified path.
 RPETemplate loadTemplate(java.lang.String configFile, java.lang.String templPath)
          Loads a template and returns a RPETemplate object.
 RPETemplate loadTemplate(java.lang.String configFile, java.lang.String baseURI, java.lang.String templateURI, Credential credential)
          Loads a document template from the given path.
 RPEDocumentSpecification makeDocSpec(java.lang.String defFile)
          Creates a document specification from a definition file.
 java.io.File packDocumentSpecification(RPEDocumentSpecification docSpec, boolean includeDynamicReferences, java.lang.String docSpecName)
          Creates an archive file that contains the document specification, the document templates that the document specification includes, and all of the style sheets that are used.
 RPETemplate replaceTemplate(RPEDocumentSpecification docSpec, RPETemplate oldTemplate, java.lang.String newTemplatePath, Credential credential, java.lang.String configFile)
          For a given document specification, this method replaces an existing document template with a new one.
 RPETemplate replaceTemplate(RPEDocumentSpecification docSpec, java.lang.String oldTemplatePath, java.lang.String newTemplatePath, Credential credential, java.lang.String configFile)
          For a given document specification, this method replaces an existing template with a new one.
 RPETemplate replaceTemplate(RPEDocumentSpecification docSpec, java.lang.String oldTemplatePath, java.lang.String newTemplatePath, java.lang.String configFile)
          For a given document specification, this method replaces an existing document template with a new one.
 void save(RPEDocumentSpecification docSpec, java.lang.String fileName)
          Saves a document specification to a file.
 void setURIResolver(com.ibm.rational.rpe.common.utils.IURIResolver uriResolver)
          Sets the IURIResolver that is to be used by this DocumentSpecificationBuilder instance.
 void stripCredentials(RPEDocumentSpecification docSpec)
          For the given document specification, this method removes any user names and passwords that are defined for templates, style sheets, and data sources.
 void syncDocumentSpecification(RPEDocumentSpecification docSpec, java.lang.String configFile)
          Synchronizes a document specification with its document templates by adding or removing data sources and variables
 void syncDocumentSpecification(RPEDocumentSpecification docSpec, java.lang.String configFile, boolean strict)
          Updates the document specification to reflect the current state of the templates.
 RPEDocumentSpecification unpackDocumentSpecification(java.net.URI file)
          Unpacks a document specification and its related artifacts from the archive file that is provided through the file argument.
 void updateProperties(com.ibm.rational.rpe.api.docspec.RPEDocumentElement docSpecElement, com.ibm.rational.rpe.api.docspec.RPEDocumentElement templateElement, java.util.List<java.lang.String> properties)
          Updates the properties of the docSpecElement with the values that are found in the properties with the same name of the templateElement.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

DSX_EXTENSION

public static final java.lang.String DSX_EXTENSION
The default extension used by RPE document specifications

See Also:
Constant Field Values
Constructor Detail

DocumentSpecificationBuilder

public DocumentSpecificationBuilder()
Method Detail

packDocumentSpecification

public java.io.File packDocumentSpecification(RPEDocumentSpecification docSpec,
                                              boolean includeDynamicReferences,
                                              java.lang.String docSpecName)
                                       throws RPEException
Creates an archive file that contains the document specification, the document templates that the document specification includes, and all of the style sheets that are used.

Parameters:
docSpec - - the document specification
includeDynamicReferences - - if true all dynamically referenced templates are downloaded and included in the archive
docSpecName - - the name to use for the new document specification. If null, a name is generated based on the current name of the document specification. If the archive is created for an RPE 1.2 WebService, the name must be docSpec.dsx. Deprecated.
Returns:
the File object representation of the archive created from the document specification resources
Throws:
RPEException

unpackDocumentSpecification

public RPEDocumentSpecification unpackDocumentSpecification(java.net.URI file)
                                                     throws RPEException
Unpacks a document specification and its related artifacts from the archive file that is provided through the file argument.

Parameters:
file - this parameter is an URI which can represent:
  • a document specification
  • an archive file that contains a document specification and related files
  • an archive file that contains a definitions file
Returns:
a document specification object
Throws:
RPEException

updateProperties

public void updateProperties(com.ibm.rational.rpe.api.docspec.RPEDocumentElement docSpecElement,
                             com.ibm.rational.rpe.api.docspec.RPEDocumentElement templateElement,
                             java.util.List<java.lang.String> properties)
Updates the properties of the docSpecElement with the values that are found in the properties with the same name of the templateElement.

Parameters:
docSpecElement -
templateElement -
properties -

syncDocumentSpecification

public void syncDocumentSpecification(RPEDocumentSpecification docSpec,
                                      java.lang.String configFile,
                                      boolean strict)
                               throws RPEException
Updates the document specification to reflect the current state of the templates. This update ensures that new variables and data sources defined in the templates are added to the document specification and deleted variables and data sources are removed. If strict is set to true and any of the templates cannot be opened, then this method throws an exception.

Parameters:
docSpec -
configFile -
strict -
Throws:
RPEException

syncDocumentSpecification

public void syncDocumentSpecification(RPEDocumentSpecification docSpec,
                                      java.lang.String configFile)
                               throws RPEException
Synchronizes a document specification with its document templates by adding or removing data sources and variables

Parameters:
docSpec - the document specification
configFile - the path to rpeconfig.xml
Throws:
RPEException - added in 1.2 to indicate synch errors in strict mode

replaceTemplate

public RPETemplate replaceTemplate(RPEDocumentSpecification docSpec,
                                   RPETemplate oldTemplate,
                                   java.lang.String newTemplatePath,
                                   Credential credential,
                                   java.lang.String configFile)
                            throws RPEException
For a given document specification, this method replaces an existing document template with a new one.

Parameters:
docSpec - the document specification object
oldTemplate - the existing document template object
newTemplatePath - the path to the document template file which replaces the existing one
configFile - the path to rpeconfig.xml
Throws:
RPEException

replaceTemplate

public RPETemplate replaceTemplate(RPEDocumentSpecification docSpec,
                                   java.lang.String oldTemplatePath,
                                   java.lang.String newTemplatePath,
                                   Credential credential,
                                   java.lang.String configFile)
                            throws RPEException
For a given document specification, this method replaces an existing template with a new one.

Parameters:
docSpec - the Document Specification object
oldTemplatePath - the path of the template to be replaced. If no template has this path nothing is replaced.
newTemplatePath - the path to the Document Template file which will replace the existing one
configFile - the path to rpeconfig.xml
Throws:
RPEException

replaceTemplate

public RPETemplate replaceTemplate(RPEDocumentSpecification docSpec,
                                   java.lang.String oldTemplatePath,
                                   java.lang.String newTemplatePath,
                                   java.lang.String configFile)
                            throws RPEException
For a given document specification, this method replaces an existing document template with a new one.

Parameters:
docSpec - the document specification object
oldTemplatePath - the path to the existing document template file
newTemplatePath - the path to the document template file which replaces the existing one
configFile - the path to rpeconfig.xml
Throws:
RPEException

loadTemplate

public RPETemplate loadTemplate(java.lang.String configFile,
                                java.lang.String templPath)
                         throws RPEException
Loads a template and returns a RPETemplate object.

Parameters:
configFile - the path to the rpeconfig.xml
templPath - the path or URI to the template
Returns:
Throws:
RPEException

loadTemplate

public RPETemplate loadTemplate(java.lang.String configFile,
                                java.lang.String baseURI,
                                java.lang.String templateURI,
                                Credential credential)
                         throws RPEException
Loads a document template from the given path.

Parameters:
configFile - the path to rpeconfig.xml
templPath - the path to the document template file
Returns:
a RPETemplate object
Throws:
RPEException

createRuntimeTemplate

public RPETemplate createRuntimeTemplate(java.lang.String configFile,
                                         com.ibm.rational.rpe.common.template.model.Template template,
                                         java.lang.String path,
                                         Credential credential)
                                  throws RPEException
Creates and returns a RPETemplate object from the given arguments.

Parameters:
configFile -
template -
path -
credential -
Returns:
Throws:
RPEException

create

public RPEDocumentSpecification create(java.lang.String configFile)
                                throws RPEException
Creates an empty document specification.

Parameters:
configFile - the path to the rpeconfig.xml configuration file
Returns:
a document specification
Throws:
RPEException

create

public RPEDocumentSpecification create(java.lang.String configFile,
                                       java.util.List<java.lang.String> templatesFile)
                                throws RPEException
Creates a new document specification from a list of document templates.

Parameters:
configFile - the path to the rpeconfig.xml configuration file
templatesFile - a List of paths to document templates
Returns:
the document specification object loaded from the specified path
Throws:
RPEException

makeDocSpec

public RPEDocumentSpecification makeDocSpec(java.lang.String defFile)
                                     throws RPEException
Creates a document specification from a definition file. Note: Only applies to local files.

Parameters:
defFile - the path to a definition file
Returns:
the newly created RPEDocumentSpecification
Throws:
RPEException

load

public com.ibm.rational.rpe.api.docspec.RPEConfiguration load(java.lang.String configPath)
                                                       throws RPEException
Loads a configuration file. Do not use directly.

Parameters:
configPath - the path to rpeconfig.xml
Returns:
the RPEConfiguration representation of the configuration file
Throws:
RPEException

load

public RPEDocumentSpecification load(java.lang.String configPath,
                                     java.lang.String docSpecPath,
                                     boolean strict)
                              throws RPEException
Loads a document specification from the specified path.

Parameters:
configPath - the path to the rpeconfig.xml configuration file
docSpecPath - the path to the document specification
strict - flag controlling whether this method ignores template access errors (strict=false)
Returns:
the document specification object loaded from the specified path
Throws:
RPEException

load

public RPEDocumentSpecification load(java.lang.String configPath,
                                     java.lang.String docSpecPath)
                              throws RPEException
Loads a document specification from the specified path.

Parameters:
configPath - the path to the rpeconfig.xml configuration file
docSpecPath - the path to the document specification
Returns:
the document specification object loaded from the specified path
Throws:
RPEException

load

public RPEDocumentSpecification load(java.lang.String configPath,
                                     java.lang.String docSpecPath,
                                     java.lang.String srcDocSpecPath,
                                     boolean strict)
                              throws RPEException
Loads a document specification from the specified path.

Parameters:
configPath - the path to the rpeconfig.xml configuration file
docSpecPath - the path to the document specification
srcDocSpecPath - the original location of the document specification. This value is equal to docSpecPath for local files.
strict - flag controlling whether this method ignores template access errors (strict=false).
Returns:
the document specification object loaded from the specified path
Throws:
RPEException

save

public void save(RPEDocumentSpecification docSpec,
                 java.lang.String fileName)
          throws RPEException
Saves a document specification to a file.

Parameters:
docSpec - a document specification object
fileName - the path to the destination file
Throws:
RPEException

stripCredentials

public void stripCredentials(RPEDocumentSpecification docSpec)
                      throws RPEException
For the given document specification, this method removes any user names and passwords that are defined for templates, style sheets, and data sources.

Parameters:
docSpec - a document specification object
Throws:
RPEException

getConfigurationForDatasource

public Feature getConfigurationForDatasource(java.lang.String configPath,
                                             java.lang.String type)
                                      throws RPEException
Builds the configuration feature for the given data source type. Do not use this directly.

Parameters:
configPath - the path to rpeconfig.xml
type - the data source type
Returns:
the configuration
Throws:
RPEException

addOutput

public RPEOutput addOutput(RPEDocumentSpecification docspec,
                           java.lang.String type,
                           java.lang.String driver)
                    throws RPEException
Adds the specified output type to the document specification. The output type must one of the supported output types. If the driver is null, then the driver for the first output type is used.

Parameters:
docspec -
Throws:
RPEException

setURIResolver

public void setURIResolver(com.ibm.rational.rpe.common.utils.IURIResolver uriResolver)
Sets the IURIResolver that is to be used by this DocumentSpecificationBuilder instance.


getURIResolver

public com.ibm.rational.rpe.common.utils.IURIResolver getURIResolver()
Returns the IURIResolver used by this DocumentSpecificationBuilder instance. The value can be null.