Chapter 5 Web Service Specification

StarOffice 8 Server - PDF Converter exposes its interface as a SOAP [SOAP=http://www.w3.org/TR/soap/] web service. As such, the interface description is provided as a WSDL [WSDL=http://www.w3.org/TR/wsdl] file. The schema of the messages exchanged via the SOAP interface are described in more detail below.

Overview

The interface has two main entry points: convert and convertMime. While the convert interface uses URLs or base64 encoded versions of the request and result files, the convertMime interface uses the mime extensions of WSDL to transfer documents as binary attachments.

The convert interface can also handle documents attached via the WS-I attachment profile, wherein an additional mime part is referenced via a cid: (content-id) URL

See www.ws-i.org/Profiles/AttachmentsProfile-1.0.html

Most language bindings will provide tools to generate language specific proxy classes from the WSDL descriptions, which can than be used to call the service in a client. Should an environment not provide such a binding, it is possible, to generate and parse the SOAP XML messages according to the SOAP and WSDL specification and the message schema given as part of the WSDL file.

The WSDL can either be obtained from a running StarOffice 8 Server - PDF Converter by appending ?WSDL to the service URL (e.g. http://localhost:8080/soserv/SOConverter?WSDL) or directly from the StarOffice 8 Server - PDF Converter installation, where it can be found at <socs-installation-dir>/engine/webapps/soserv/WEB-INF/Converter.wsdl.

Description of the API

Note –

For StarOffice 8 Server - PDF Converter Update 10 the API of the Conversion Webservice had to be changed. In case your client applications do not work any longer with StarOffice 8 Server - PDF Converter Update 10, you need to recompile them using the current WSDL file. To obtain the version of your StarOffice 8 Server - PDF Converter installation, refer to the file <socs-installation-dir>/program/versionrc (version.ini on Windows).

The XML that the StarOffice 8 Server - PDF Converter uses to send and to receive requests from the server is defined in a WSDL file. This file contains definitions for the following elements.

<option>

An <option> element of type optionsType has name and value attributes. The following name and value pairs are supported by the StarOffice 8 Server - PDF Converter:
- settings.sourceFileExtension
  
  Always supply the file extension (without the dot) of the source file. Otherwise, some file types will not be detected and converted correctly.
- pdf.encryptDocument
  
  Values true or false, or omitted, with a default value of false, see Sample JSP.
- pdf.openPassword
  
  A string that can contain a password, see Sample JSP. This property value is ignored unless pdf.encryptDocument is set to true.
- pdf.restrictPermissions
  
  Values true or false, or omitted, with a default value of false, see Sample JSP.
- pdf.permissionPassword
  
  A string that can contain a password, see Sample JSP. This property value is ignored unless pdf.restrictPermissions is set to true.
- pdf.printing
  
  Values 0, 1, 2, or omitted, see Sample JSP. This property value is ignored unless pdf.restrictPermissions is set to true.
  - 0: printing not permitted
  - 1: permit low resolution printing
  - 2: permit high resolution printing
- pdf.changes
  
  Values 0, 1, 2, 3, 4, or omitted, see Sample JSP. This property value is ignored unless pdf.restrictPermissions is set to true.
  - 0: not changes permitted
  - 1: inserting, deleting, rotating pages permitted
  - 2: filling in form fields permitted
  - 3: commenting permitted
  - 4: any changes permitted, except extraction of content
- pdf.enableCopyingOfContent
  
  Values true or false, or omitted, default false, see Sample JSP. This property value is ignored unless pdf.restrictPermissions is set to true.
- pdf.enableTextAccessForAccessibilityTools
  
  Values true or false, or omitted, default false, see Sample JSP. This property value is ignored unless pdf.restrictPermissions is set to true.
- pdf.compression
  
  Possible values are lossless or jpeg, default is lossless. If the value is set to jpeg, the additional option.
  - pdf.jpegQuality is evaluated, which defines the JPEG compression of images.
- pdf.tagged
  
  Values true or false, or omitted, default false, see Sample JSP.
- pdf.archive
  
  Create PDF/A-1. Values true or false, or omitted, default false, see Sample JSP.
- pdf.hybrid
  
  Values true or false, or omitted, default false, see Sample JSP.
- pdf.exportNotes
  
  Values true or false, or omitted, default false, see Sample JSP.
- pdf.useTransitions
  
  Values true or false, or omitted, default false, see Sample JSP.
- pdf.reduceResolution
  
  Values true or false, or omitted, default false, see Sample JSP.
  - pdf.maxResolution
    
    A string that contains the maximum number of pixels per inch.
- pageRange
  
  A string with a format that is described in Sample JSP.
For language bindings that do not support the array structure of the option element, you can use the optionString element. This element takes a string encoded form of the options array. The encoding is similar to that of an HTTP query, that is, opt_name1=value1&opt_name2=value2&...

If both an array of option elements and an optionString are in a message, the content of the optionString element is ignored and the values of the option elements are used.
<convertMime>

Contains the <targetType> element with the only allowed and required content of PDF, as well as the <option> element, listing the optionsType arguments above.
<convert>

Contains the <targetType> element with the required content of PDF, the <sourceURL> or <sourceDocument> elements, as well as the required <option> element. The content of the <sourceDocument> element can be a base64Binary or as wsiAttachment.
<convertResponse>

Contains a status message about the conversion of the document, and either a <resultURL>element or a <resultDocument> element. The content of the <resultDocument> element can be a base64Binary or a wsiAttachment.
<convertMimeResponse>

Contains the <status> element.
<conversionFault>

Contains the <errorCode>element and a message. The following is a list of the possible errorCodevalues:
- ERROR_UNEXPECTED = -1
- ERROR_SERVER = 1
- ERROR_OPEN = 2
- ERROR_PROCESS = 3
- ERROR_EXPORT = 4
- ERROR_POSTPROCESS = 5
- ERROR_DESTROYED = 7
Note –
Only ERROR_OPEN, cannot read the document, is currently relevant to a user.
The above elements are then used to define the messages “convertRequest”, “convertMimeRequest” which also contains a base64Binary defining the source document, “convertResponse”, “convertMimeResponse”, and “conversionError”.

WSDL

<?xml version="1.0" encoding="UTF-8"?>
<!--
 Copyright 2005 Sun Microsystems, Inc. All rights reserved.
 SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
-->
<definitions 
    xmlns="http://schemas.xmlsoap.org/wsdl/" 
    xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
    xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
    xmlns:mime="http://schemas.xmlsoap.org/wsdl/mime/"
    xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"
    xmlns:ns2="urn:soserv:Converter/types"  
    xmlns:tns="urn:soserv:Converter/wsdl"     
    targetNamespace="urn:soserv:Converter/wsdl"
    name="Converter" >

<types>

<xsd:schema     
    xmlns:tns="urn:soserv:Converter/types"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" 
    xmlns:wsi="http://ws-i.org/profiles/basic/1.1/xsd"
    elementFormDefault="qualified"
    targetNamespace="urn:soserv:Converter/types">

    <xsd:simpleType name="swaRef"> 
            <xsd:restriction base="xsd:anyURI" /> 
    </xsd:simpleType> 
        
    <xsd:complexType name="optionsType">
        <xsd:attribute name="name"  type="xsd:string"/>
        <xsd:attribute name="value" type="xsd:string"/>                
    </xsd:complexType>
    
    <!-- struct which holds information related to a conversion job -->    
    <xsd:element name="convertMime">        
        <xsd:complexType>
            <xsd:sequence>
                <xsd:element name="targetType" type="xsd:string" nillable="true"/>
                <xsd:element name="option" type="tns:optionsType" minOccurs="0" maxOccurs="unbounded"/>
                <xsd:element name="optionString" type="xsd:string" minOccurs="0" maxOccurs="1"/>
            </xsd:sequence>
        </xsd:complexType>            
    </xsd:element>

    <xsd:element name="convert">        
        <xsd:complexType>
            <xsd:sequence>
                <xsd:element name="sourceURL" type="xsd:anyURI" nillable="true"/>
                <xsd:element name="sourceDocument" type="xsd:base64Binary" nillable="true"/>
                <xsd:element name="wsiAttachment" type="tns:swaRef" nillable="true"/>
                <xsd:element name="targetType" type="xsd:string" nillable="true"/>
                <xsd:element name="option" type="tns:optionsType" minOccurs="0" maxOccurs="unbounded"/>
                <xsd:element name="optionString" type="xsd:string" minOccurs="0" maxOccurs="1"/>
            </xsd:sequence>
        </xsd:complexType>            
    </xsd:element>
        
    <xsd:element name="convertResponse"> 
        <xsd:complexType>
            <xsd:sequence>    
                <xsd:element name="status" type="xsd:string" nillable="true"/>
                <xsd:element name="resultURL" type="xsd:anyURI" nillable="true"/>
                <xsd:element name="resultDocument" type="xsd:base64Binary" nillable="true"/>
                <xsd:element name="wsiAttachment" type="tns:swaRef" nillable="true"/>
            </xsd:sequence>
        </xsd:complexType>
    </xsd:element>

    <xsd:element name="convertMimeResponse"> 
        <xsd:complexType>
            <xsd:sequence>    
                <xsd:element name="status" type="xsd:string" nillable="true"/>
                <xsd:element name="mimeType" type="xsd:string" nillable="true"/>
            </xsd:sequence>
        </xsd:complexType>
    </xsd:element>
    
    <xsd:element name="conversionFault">
        <xsd:complexType>
            <xsd:sequence>
                <xsd:element name="errorCode" type="xsd:int"/>
                <xsd:element name="message" type="xsd:string"/>
            </xsd:sequence>
        </xsd:complexType>
    </xsd:element>

</xsd:schema>
</types>

<message name="convertRequest">
    <part name="parameters" element="ns2:convert"/>
</message>
<message name="convertResponse">
    <part name="result" element="ns2:convertResponse"/>
</message>

<message name="convertMimeRequest">
    <part name="parameters" element="ns2:convertMime"/>
    <part name="mimeAttachment" type="xsd:base64Binary"/>
</message>
<message name="convertMimeResponse">
    <part name="result" element="ns2:convertMimeResponse"/>
    <part name="mimeAttachment" type="xsd:base64Binary"/>
</message>

<message name="conversionError">
    <part name="fault"  element="ns2:conversionFault"/>
</message>

<!-- service endpoint interface for conversion service -->
<portType name="ConverterSEI">
    <operation name="convert">
        <documentation>...</documentation>
        <input message="tns:convertRequest"/>
        <output message="tns:convertResponse"/>
        <fault name="conversionError" message="tns:conversionError"/>
    </operation>
    <operation name="convertMime">
        <documentation>...</documentation>
        <input message="tns:convertMimeRequest"/>
        <output message="tns:convertMimeResponse"/>
        <fault name="conversionError" message="tns:conversionError"/>
    </operation>    
</portType>

<!-- soap binding -->
<binding name="ConverterSEIBinding" type="tns:ConverterSEI">
    <soap:binding transport="http://schemas.xmlsoap.org/soap/http" style="document"/>

    <operation name="convert">
        <soap:operation soapAction=""/>
        <input>
            <soap:body use="literal"/>
        </input>
        <output>
            <soap:body use="literal"/>
        </output>    
        <fault name="conversionError">
            <soap:fault name="conversionError" use="literal"/>
        </fault>            
    </operation>

    <operation name="convertMime">
        <soap:operation soapAction=""/>
        <input>
            <mime:multipartRelated>
                <mime:part>
                    <soap:body parts="parameters" use="literal"/>
                </mime:part>
                <mime:part>
                    <mime:content part="mimeAttachment" type="application/octet-stream"/>
                </mime:part>
            </mime:multipartRelated>
        </input>
        <output>
            <mime:multipartRelated> 
                <mime:part>
                    <soap:body parts="result" use="literal"/>
                </mime:part>
                <mime:part>
                    <mime:content part="mimeAttachment" type="application/octet-stream"/>
                </mime:part>
            </mime:multipartRelated>        
        </output>        
        <fault name="conversionError">
            <soap:fault name="conversionError" use="literal"/>
        </fault>                    
    </operation>
</binding>

<service name="Converter">
    <port name="ConverterSEIPort" binding="tns:ConverterSEIBinding">
      <soap:address location="http://localhost:8080/soserv/SOConverter"
       xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"/>
    </port>
</service>
  
</definitions>

包含在

尋找其他文件

熱門支援資源

Chapter 5 Web Service Specification

Overview

Description of the API

WSDL