Table of Contents

• 1.1 Rationale

• 2.1 Model Terminology
• 2.1.1 Attribute
• 2.1.2 Client
• 2.1.3 Document
• 2.1.4 Element
• 2.1.5 Job
• 2.1.6 Object
• 2.1.7 Transformer
• 2.2 Conformance Terminology

• 3.1 Transformer Model
• 3.2 Transformer Object
• 3.2.1 TransformerStatus
• 3.2.2 TransformerDescription

• 4.1 GetTransformerElements
• 4.2 CreateJob
• 4.3 CloseJob
• 4.4 GetJobElements
• 4.5 CancelJob
• 4.6 AddDocumentByReference
• 4.7 FetchDocumentDataByPull
• 4.8 GetDocumentElements
• 4.9 CancelDocument

Printer Working Group

Transform Interface - Strawman Proposal

Technical Brief

Status: Initial

9 August 2004

Abstract: This is a strawman proposal for a new PWG Transform Interface. This proposal imports the semantics and schema of the existing Job and Document objects from the PWG Semantic Model [PWG5105.1]. This proposal defines one new object - Transformer - analogous to the existing Printer object in IPP/1.1 and Semantic Model/1.0. This proposal defines one new protocol interface with nine operations (all mandatory for all Clients and Transformers).

This document is available at:

ftp://ftp.pwg.org/pub/pwg/BOFs/tfm/tb-tfmstrawman-20040809.htm

1 Introduction

This is a strawman proposal for a new PWG Transform Interface. This proposal imports the semantics and schema of the existing Job and Document objects from the PWG Semantic Model [PWG5105.1]. This proposal defines one new object - Transformer - analogous to the existing Printer object in IPP/1.1 and Semantic Model/1.0. This proposal defines one new protocol interface with nine operations (all mandatory for all Clients and Transformers).

1.1 Rationale

This strawman proposal adopts the design approach of a new Transformer object, as opposed to a severely restricted Printer object, to add support for the transform function in the PWG Semantic Model. The restricted Printer object would have broken semantics (since all print jobs typically eventually result in hardcopy) and a whole class of meaningless elements (the JobProcessing default/supported elements).

2 Terminology

2.1 Model Terminology

2.1.1 Attribute

This document imports the definition and semantics of an Attribute from [RFC2911].

2.1.2 Client

A Client is the software on a host system that submits a document transformation Job to a Transformer on the same or another system.

2.1.3 Document

This document imports the definition and semantics of a Document from [PWG5100.5] and [PWG5105.1].

2.1.4 Element

This document imports the term Element from [PWG5105.1], where it is typically used as an XML synonym for Attribute in [RFC2911].

2.1.5 Job

This document imports the definition and semantics of a Job from [RFC2911] and [PWG5105.1].

2.1.6 Object

This document imports the definition and semantics of an Object from [RFC2911] and [PWG5105.1].

2.1.7 Transformer

This document defines one extension object - Transformer - for addition to the PWG Semantic Model [PWG5105.1]. A Transformer is the software on a host system that supports creation, processing, query, and retrieval of document transformation Jobs.

2.2 Conformance Terminology

The key words "MUST", "MUST NOT", "REQUIRED", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as defined in [RFC2119].

3 Model Overview

3.1 Transformer Model

The following diagram shows the object containment in the model:

|----------------------------------------------------------|
|                                                          |
|   Transformer (exactly one)                              |
|   - REQUIRED elements                                    |
|   - OPTIONAL elements                                    |
|                                                          |
|   |------------------------------------------------------|
|   |                                                      |
|   |   Job (exactly one)                                  |
|   |   - REQUIRED elements                                |
|   |   - OPTIONAL elements                                |
|   |                                                      |
|   |   |--------------------------------------------------|
|   |   |                                                  |
|   |   |   Document (one or more)                         |
|   |   |   - REQUIRED elements                            |
|   |   |   - OPTIONAL elements                            |
|   |   |                                                  |
|   |   |--------------------------------------------------|
|   |------------------------------------------------------|
|----------------------------------------------------------|

3.2 Transformer Object

This proposal defines one new object - Transformer - analogous to the existing Printer object in IPP/1.1 [RFC2911] and Semantic Model [PWG5105.1].

3.2.1 TransformerStatus

By analogy to the PrinterStatus group in the Printer object, the TransformerStatus group should include the following:

TransformerCurrentDateTime (xsd:dateTime)
TransformerMessageDateTime (xsd:dateTime)
TransformerIsAcceptingJobs (xsd:boolean)
TransformerState (pwg-sm:TransformerStateWKV)
TransformerStateMessage (xsd:string)
TransformerStateReasons (xsd:string)
TransformerQueuedJobCount (xsd:int)

3.2.2 TransformerDescription

By analogy to the PrinterDescription group in the Printer object, the TransformerDescription group should include the following:

DocumentCharsetSupported (pwg-sm:CharsetWKV)
DocumentDigitalSignatureSupported (pwg-sm:DocumentDigitalSignatureWKV)
DocumentFormatSupported (pwg-sm:DocumentFormatWKV)
DocumentFormatDetailsSupported (pwg-sm:DocumentFormatDetails)
DocumentNaturalLanguageSupported (pwg-sm:NaturalLanguageWKV)
TransformerAuthenticationSupported (pwg-sm:UriAuthenticationWKV)
TransformerColorSupported (pwg-sm:ColorWKV)
TransformerCompressionSupported (pwg-sm:CompressionWKV)
TransformerInfo (xsd:string)
TransformerMessageFromOperator (xsd:string)
TransformerReferenceUriSchemesSupported (xsd:string)
TransformerSecuritySupported (pwg-sm:UriSecurityWKV)

4 Transform Interface

4.1 GetTransformerElements

GetTransformerElements (requestedElements : RequestedElements)
    statusString : StatusString,
    unsupportedElements : UnsupportedElements,
    transformer : Transformer

Description:

This operation allows a Client to query a Transformer for requested elements of the Transformer (e.g., capabilities and defaults).

Parameters:

requestedElements : pwg-sm:RequestedElements

- this REQUIRED parameter specifies a list of fully qualified names of requested elements of the Transformer object. Conforms to definition in Semantic Model [PWG-SM] 'PwgCommon.xsd'.

Returns:

statusString : pwg-sm:StatusString

- a keyword returned by the Transformer, specifying the status of the operation execution at the time of response. Conforms to definition in Semantic Model [PWG-SM] 'PwgCommon.xsd'.

unsupportedElements : pwg-sm:UnsupportedElements

- a list that contains the object elements that, as specified in this operation, are not supported by this Transformer. If all requested elements are supported, then this element is empty. Conforms to definition in Semantic Model [PWG-SM] 'PwgCommon.xsd'.

transformer : pwg-sm:Transformer

- a Transformer object instance that contains (at least) all of the requested elements that are supported by this Transformer. If statusString indicates failure, then this element is empty. Conforms to definition in Semantic Model [PWG-SM] 'Transformer.xsd'.

4.2 CreateJob

CreateJob (requestedDocumentFormatDetails : DocumentFormatDetails,
    jobDescription : JobDescription)
    statusString : StatusString,
    unsupportedElements : UnsupportedElements,
    jobId : int

Description:

This operation allows a Client to create a new Job instance on this Transformer.

Parameters:

requestedDocumentFormatDetails : pwg-sm:DocumentFormatDetails

- this REQUIRED parameter specifies the requested output document format for this transformation Job. If the Transformer does not support the requestedDocumentFormatDetails, then it shall return ClientErrorAttributesOrValuesNotSupported in statusString. Conforms to definition in Semantic Model [PWG-SM] 'PwgCommon.xsd'.

jobDescription : pwg-sm:JobDescription

- this REQUIRED parameter specifies a description of this Job, or is empty if no description elements are needed. Conforms to definition in Semantic Model [PWG-SM] 'JobDescription.xsd'.

Returns:

statusString : pwg-sm:StatusString

- a keyword returned by the Transformer, specifying the status of the operation execution at the time of response. Conforms to definition in Semantic Model [PWG-SM] 'PwgCommon.xsd'.

unsupportedElements : pwg-sm:UnsupportedElements

- a list that contains the object elements that, as specified in this operation, are not supported by this Transformer. If all requested elements are supported, then this element is empty. Conforms to definition in Semantic Model [PWG-SM] 'PwgCommon.xsd'.

jobId : pwg-sm:JobId

- a unique identifier for the Job on this Transformer. If statusString indicates failure, then this element is empty. Conforms to definition in Semantic Model [PWG-SM] 'PwgCommon.xsd'.

4.3 CloseJob

CloseJob (jobId : int)
    statusString : StatusString

Description:

This operation allows a Client to close an open Job instance on this Transformer (i.e., to schedule the Job for processing).

Parameters:

jobId : pwg-sm:JobId

- this REQUIRED parameter specifies a unique identifier for the Job on this Transformer. Conforms to definition in Semantic Model [PWG-SM] 'PwgCommon.xsd'.

Returns:

statusString : pwg-sm:StatusString

- a keyword returned by the Transformer, specifying the status of the operation execution at the time of response. Conforms to definition in Semantic Model [PWG-SM] 'PwgCommon.xsd'.

4.4 GetJobElements

GetJobElements (jobId : int,
    requestedElements : RequestedElements)
    statusString : StatusString,
    unsupportedElements : UnsupportedElements,
    job : Job

Description:

This operation allows a Client to query a Transformer for requested elements of the specified Job object.

Parameters:

jobId : pwg-sm:JobId

- this REQUIRED parameter specifies a unique identifier for the Job on this Transformer. Conforms to definition in Semantic Model [PWG-SM] 'PwgCommon.xsd'.

requestedElements : pwg-sm:RequestedElements

- this REQUIRED parameter specifies a list of fully qualified names of requested elements of the Job object. Conforms to definition in Semantic Model [PWG-SM] 'PwgCommon.xsd'.

Returns:

statusString : pwg-sm:StatusString

- a keyword returned by the Transformer, specifying the status of the operation execution at the time of response. Conforms to definition in Semantic Model [PWG-SM] 'PwgCommon.xsd'.

unsupportedElements : pwg-sm:UnsupportedElements

- a list that contains the object elements that, as specified in this operation, are not supported by this Transformer. If all requested elements are supported, then this element is empty. Conforms to definition in Semantic Model [PWG-SM] 'PwgCommon.xsd'.

job : pwg-sm:Job

- a Job object instance that contains (at least) all of the requested elements that are supported by this Transformer. If statusString indicates failure, then this element is empty. Conforms to definition in Semantic Model [PWG-SM] 'Job.xsd'.

4.5 CancelJob

CancelJob (jobId : int)
    statusString : StatusString

Description:

This operation allows a Client to cancel a Job instance on this Transformer (i.e., to abandon the Job).

Parameters:

jobId : pwg-sm:JobId

- this REQUIRED parameter specifies a unique identifier for the Job on this Transformer. Conforms to definition in Semantic Model [PWG-SM] 'PwgCommon.xsd'.

Returns:

statusString : pwg-sm:StatusString

- a keyword returned by the Transformer, specifying the status of the operation execution at the time of response. Conforms to definition in Semantic Model [PWG-SM] 'PwgCommon.xsd'.

4.6 AddDocumentByReference

AddDocumentByReference (jobId : int,
    referenceURI : URI,
    documentDescription : DocumentDescription)
    statusString : StatusString,
    unsupportedElements : UnsupportedElements,
    documentNumber : int

Description:

This operation allows a Client to add a new Document instance to the specified Job instance on this Transformer.

Parameters:

jobId : pwg-sm:JobId

- this REQUIRED parameter specifies a unique identifier for the Job on this Transformer. Conforms to definition in Semantic Model [PWG-SM] 'PwgCommon.xsd'.

referenceURI : xsd:anyURI

- this REQUIRED parameter specifies the source URI for the document to be added to this Job instance on the Transformer. Conforms to the generic URI syntax definition in [RFC2396].

documentDescription : pwg-sm:DocumentDescription

- this REQUIRED parameter specifies a description of this Document, or is empty if no description elements are needed. Conforms to definition in Semantic Model [PWG-SM] 'DocumentDescription.xsd'.

Returns:

statusString : pwg-sm:StatusString

- a keyword returned by the Transformer, specifying the status of the operation execution at the time of response. Conforms to definition in Semantic Model [PWG-SM] 'PwgCommon.xsd'.

unsupportedElements : pwg-sm:UnsupportedElements

- a list that contains the object elements that, as specified in this operation, are not supported by this Transformer. If all requested elements are supported, then this element is empty. Conforms to definition in Semantic Model [PWG-SM] 'PwgCommon.xsd'.

documentNumber : pwg-sm:DocumentNumber

- a unique identifier for the Document instance within the specified Job instance on this Transformer. If statusString indicates failure, then this element is empty. Conforms to definition in Semantic Model [PWG-SM] 'PwgCommon.xsd'.

4.7 FetchDocumentDataByPull

FetchDocumentDataByPull (jobId : int,
    documentNumber : int)
    statusString : StatusString,
    dataSourceURIs : DataSourceURIs

Description:

This operation allows a Client to retrieve a list of one or more sources of transformed document data for the Document instance of the specified Job instance on this Transformer.

Parameters:

jobId : pwg-sm:JobId

- this REQUIRED parameter specifies a unique identifier for the Job on this Transformer. Conforms to definition in Semantic Model [PWG-SM] 'PwgCommon.xsd'.

documentNumber : pwg-sm:DocumentNumber

- this REQUIRED parameter specifies a unique identifier for the Document instance within the specified Job instance on this Transformer. Conforms to definition in Semantic Model [PWG-SM] 'PwgCommon.xsd'.

Returns:

statusString : pwg-sm:StatusString

- a keyword returned by the Transformer, specifying the status of the operation execution at the time of response. Conforms to definition in Semantic Model [PWG-SM] 'PwgCommon.xsd'.

dataSourceURIs : pwg-sm:DataSourceURIs

- a list of sources for the transformed document data for the specified Document instance. If statusString indicates failure, then this element is empty. Conforms to definition in Semantic Model [PWG-SM] 'PwgCommon.xsd'.

4.8 GetDocumentElements

GetDocumentElements (jobId : int,
    documentNumber : int,
    requestedElements : RequestedElements)
    statusString : StatusString,
    unsupportedElements : UnsupportedElements,
    job : Job

Description:

This operation allows a Client to query a Transformer for requested elements of the specified Document object.

Parameters:

jobId : pwg-sm:JobId

- this REQUIRED parameter specifies a unique identifier for the Job on this Transformer. Conforms to definition in Semantic Model [PWG-SM] 'PwgCommon.xsd'.

documentNumber : pwg-sm:DocumentNumber

- this REQUIRED parameter specifies a unique identifier for the Document instance within the specified Job instance on this Transformer. Conforms to definition in Semantic Model [PWG-SM] 'PwgCommon.xsd'.

requestedElements : pwg-sm:RequestedElements

- this REQUIRED parameter specifies a list of fully qualified names of requested elements of the Document object. Conforms to definition in Semantic Model [PWG-SM] 'PwgCommon.xsd'.

Returns:

statusString : pwg-sm:StatusString

- a keyword returned by the Transformer, specifying the status of the operation execution at the time of response. Conforms to definition in Semantic Model [PWG-SM] 'PwgCommon.xsd'.

unsupportedElements : pwg-sm:UnsupportedElements

- a list that contains the object elements that, as specified in this operation, are not supported by this Transformer. If all requested elements are supported, then this element is empty. Conforms to definition in Semantic Model [PWG-SM] 'PwgCommon.xsd'.

document : pwg-sm:Document

- a Document object instance that contains (at least) all of the requested elements that are supported by this Transformer. If statusString indicates failure, then this element is empty. Conforms to definition in Semantic Model [PWG-SM] 'Document.xsd'.

4.9 CancelDocument

CancelDocument (jobId : int,
    documentNumber : int)
    statusString : StatusString

Description:

This operation allows a Client to cancel a Document instance within the specified Job instance on this Transformer (i.e., to abandon the Document).

Parameters:

jobId : pwg-sm:JobId

- this REQUIRED parameter specifies a unique identifier for the Job on this Transformer. Conforms to definition in Semantic Model [PWG-SM] 'PwgCommon.xsd'.

documentNumber : pwg-sm:DocumentNumber

- this REQUIRED parameter specifies a unique identifier for the Document instance within the specified Job instance on this Transformer. Note that this document number will NOT be reused later in this document transformation Job. Conforms to definition in Semantic Model [PWG-SM] 'PwgCommon.xsd'.

Returns:

statusString : pwg-sm:StatusString

- a keyword returned by the Transformer, specifying the status of the operation execution at the time of response. Conforms to definition in Semantic Model [PWG-SM] 'PwgCommon.xsd'.