Prior to QuarkXPress Server 9.0, you had to use different URL constructions when sending
requests to an instance of QuarkXPress Server Manager in a QPS installation than you did
when sending requests to a free-standing instance of QuarkXPress Server Manager. In
versions 9.0 and later, both can use /qxpsm/request/ after [port]/ .
You can now use both absolute and relative paths when you modify a project with SDK
objects or classes. Relative paths are almost always relative to the document pool. If you
use multiple QuarkXPress Server instances, you should use a common document pool.
Interpreting the QXP Server Manager response
When QuarkXPress Server Manager successfully processes a request through the HTTP
interface, the response is the same as QuarkXPress Server's response unless the user has
supplied additional parameters to QuarkXPress Manager. For more information, see
"Working with QuarkXPress Server Manager" in A Guide to QuarkXPress Server.
If an error occurs, QuarkXPress Server Manager retries the request, either on the same
QuarkXPress server instance or a different one (depending on the error and global settings
established in the QuarkXPress Server Manager client). If QuarkXPress Server Manager
cannot process the request, it returns an XML response describing the error, plus any
header error codes returned by QuarkXPress Server. For example:
<?xml version="1.0" encoding="UTF-8" ?>
<error>
<httpresponsecode>500</httpresponsecode>
<xpressservererrorcode>-43</xpressservererrorcode>
<xpressservererrormessage>File not found.</xpressservererrormessage>
<xpressserverextendedmessage> <![CDATA[ Error #-43 - File not found. ]]>
</xpressserverextendedmessage>
<xpressservermanagererrorcode>M8000001</xpressservermanagererrorcode>
<xpressservermanagererrormessage>The server could not locate the specified
file.
</xpressservermanagererrormessage>
</error>
HTTP GET and POST Requests
The topics below describe how you can use HTML to interact with QuarkXPress Server.
QuarkXPress Server supports both the GET and POST HTML methods. When you use the
GET method, the browser encodes form data into a URL. When you use the POST method,
form data is passed within the message body. Use the GET method only when the form
QXP SERVER 9.2 WEB INTEGRATION GUIDE | 15
GETTING STARTED
processing is idempotent. In short: GET is for retrieving data, whereas POST can involve
storing or updating data, ordering a product, or sending an e-mail.
Using HTTP GET with QXP Server
Use HTML like the following to specify a server and port where you want to send a request.
You can specify the name of the target project, the output type, and a scaling value. You
can specify the name of a box and the path of a text or picture files to import into that
box, as long as the file's path is on the server's file system. You can also use HTML like the
following to specify the page number and layout number of the project.
The form section of the HTML should begin with the following line of code:
<form id = form1 method="GET" enctype="application/x-www-form-urlencoded">
For both GET and POST, the browser constructs a form data set and encodes it according
to the ENCTYPE attribute (you can use multipart/form-data for POST and
application/x-www-form-urlencoded (the default) for both POST and GET).
To create fields that let the user specify the server IP address, the port, and the project
with the QuarkXPress Server Manager computer's IP address and [port] with the
QuarkXPress Server Manager port number.
These classes can be chained together to form compound QuarkXPress Server requests.
The sample applications (see "Sample applications") show how to use these classes to invoke
a QuarkXPress Server command and manipulate the response.
QXP SERVER 9.2 WEB INTEGRATION GUIDE | 19
GETTING STARTED
For more information, see "Using the Web interface." In addition to the classes listed there,
the Web services interface includes the following:
•
RequestService processes QuarkXPress Server requests. This object's generic
processRequest() method takes a QRequestContext argument and returns a
QContentData object containing the response. For more information, see the sample
applications and "Using the Web interface."
•
QRequestContext is the argument you pass to RequestService's generic
processRequest() method.This object contains settings which must be set once per
request. Set all chained requests inside the request context.
•
QRequest is the base class for all request objects (such as PDFRenderRequest).
Consequently, all request objects share some common data members.
•
RequestParameters is a generic class for executing any request and for adding dynamic
properties to a request.
•
NameValueParam is a generic class for adding dynamic properties to a request. This class
is specifically for requests that take a box's name and/or ID as the parameter name and
the box's content as the value.
QRequestContext
Description
•
QContentData is the response returned when a request is executed. QContentData is a
hyperlink that follows the same pattern as the classes above.
•
QException is the exception class for QuarkXPress Server Manager. Web services returns
a QException object if an error occurs with any Web service method. You can use try/catch
blocks to handle QException objects.
If you've written a Server XTensions module, you can extend the WIG to include any
changes it makes to the Modifier DTD by simply modifying an XML file and regenerating
the stubs.
To exclude empty tags in the request HTML, set the value of the appropriate variable to
null.
For Javadocs, WSDL schemas, and JSP samples, see the Welcome page that displays when
you launch QuarkXPress Server Manager.
The following topics describe the general Web services classes.
An argument passed to RequestService. Contains settings that must be set once per request. All
chained requests must be set inside the request context.
Web service data objectType
NameMembers
documentName
20 | QXP SERVER 9.2 WEB INTEGRATION GUIDE
DescriptionTypes
File or object name on which the command will be rendered.String
GETTING STARTED
serverName
serverPort
userName
userPassword
maxRetries
requestTimeout
useCache
responseAsURL
bypassFileInfo
context
String
Integer
Boolean
Boolean
Boolean
Server name. Default is NULL. Load balancer searches for the host
itself in this case.
Port at which the desired server is listening.Integer
Server admin username.String
Server admin password.String
Max number of times to try executing the command before
returning failure.
Max time out in milliseconds.Integer
Indicates whether the cache should be checked for an existing
result or if the command should be executed again.
This value indicates whether the server should send the response
as-is (text or binary) or store the response on the server and return
its location as a URL. Because the object model works on SOAP,
which can be slow when transferring large binary files, you might
choose to set this value to "true" if you suspect that the response
is going to be several megabytes or larger.
Indicates whether file info should be fetched before executing the
command.
Context in which the command is being executed.String
//Create the service and call it QRequestContext object
RequestService svc = new RequestService();
com.quark.qxpsm.QContentData qc = svc.processRequest(rc);
Web service called to process the QuarkXPress Server request. RequestService has a generic method
named processRequest() that takes QRequestContext as an argument and returns QContentData
as the QuarkXPress Server response.
Web serviceType
processRequest
Processes the request context and returns the result.
QuarkXPress Server request is instances of request objects chained
together.
DescriptionTypeParameter
QRequestContextrequestCmd
Argument passed to
RequestService. Contains settings
that must be set once per request.
All chained requests are set inside
the request context.
QXP SERVER 9.2 WEB INTEGRATION GUIDE | 21
GETTING STARTED
createSession
closeAlldocs
closeDoc
Creates a new session and returns a session ID.
DescriptionTypeParameter
timeout
Closes all open documents in the session without saving them. If the session
does not exist, an error is returned. If an error occurs while closing the
document, it is logged and the document is marked closed in the internal
cache. No error is returned.
sessionId
Closes the specified document without saving it. If the session does not exist,
an error is returned. If the document is not open, and error is returned. If the
document is open in another session, an error is returned. If an error occurs
while closing the document, it is logged and the document is marked closed
in the internal cache. No error is returned.
Long
String
Timeout for the session in
milliseconds. If no call is executed
in that time, session is expired and
all the open documents in that
session are closed without saving. If
0 is passed as value of timeout,
default timeout is used. If a negative
value is passed as timeout, the
session never expires.
DescriptionTypeParameter
Session whose documents are to be
closed.
closeSession
getOpenDocs
getOpenSessions
getPreferences
setPreferences
DescriptionTypeParameter
docName
sessionId
Closes the specified session. If the session does not exist, an error is returned.
If any documents are still open in the session, an error is returned.
sessionId
Gets all the open documents in the session. If the session does not exist, an
error is returned.
sessionId
Gets all open sessions.
Gets QuarkXPress Server preferences.
Sets QuarkXPress Server preferences.
String
String
Document to be closed.String
Session in which document was
opened.
DescriptionTypeParameter
Session to be closed.String
DescriptionTypeParameter
Session whose open documents are
sought.
getXPressDOM
Creates a DOM for the specified document.
22 | QXP SERVER 9.2 WEB INTEGRATION GUIDE
GETTING STARTED
newDoc
Creates a new document for modification and keeps it open until further
notice. The document is created with a single layout. To create a more complex
document, use the processRequestEx API. If a document with the same name
is already open, an error is returned. If the session does not exist, an error is
returned.
DescriptionTypeParameter
docName
jobJacketName
jobTicketName
host
String
String
String
Document to be opened for
modification. Provide the name
only. You can proivde a relative
path when you save the document.
Name of the Job Jackets file to be
used. The Job Jackets file is assumed
to be already available on the
QuarkXPress server computer.
Name of the Job Ticket to be used.String
The QuarkXPress Server instance
that should be used for this
document modification. If null, this
value is supplied by the load
balancer. If the indicated server is
not an active registered server, an
error is thrown.
openDoc
port
sessionId
Opens the specified document and keeps it open until further notice. If the
document is already open, an error is returned. If the session does not exist,
an error is returned.
docName
host
port
sessionId
Integer
String
String
String
Integer
String
The port for the server specified in
the host parameter.
Session in which the document
should be opened.
DescriptionTypeParameter
Document (along with relative path
if required) to be opened for
modification.
QuarkXPress Server instance which
should be used for this document
modification. If null, this value is
supplied by the load balancer. If the
indicated server is not an active
registered server, an error is thrown.
The port for the server specified in
the host parameter.
Session in which the document
should be opened.
processRequestEx
Executes the request context. If a session ID is specified, the document is kept
open after the request is executed. If no session ID is specified, the request is
QXP SERVER 9.2 WEB INTEGRATION GUIDE | 23
GETTING STARTED
executed normally without keeping the document open. If the document is
open in another session, an error is returned. If the document is marked dirty,
an error is returned (a document is marked dirty when the server that opened
the document has become inactive; in such a case, the document must be
closed and opened again).
DescriptionTypeParameter
saveAllDocs
QRequestContextreqContextObj
sessionId
Saves all open documents in the session. The documents are saved one by
one. If error occurs while saving a document, an error is returned immediately
and the rest of the documents remain unsaved. If a document is marked dirty,
an error is returned (a document is marked dirty when the server that opened
the document has become inactive; in such a case, the document must be
closed and opened again).
relativePath
String
String
Request to be executed.
Session in which the request should
be executed. This value may be null.
If a session ID is provided, the
document is kept open. If no session
ID is provided, the request is
executed normally, as if
processRequest had been called.
DescriptionTypeParameter
Relative path where open
documents should be saved. If this
value is provided, copies of open
documents with changes made so
far are saved in the new location.
The open documents are not saved
but have all of the changes made so
far.
saveDoc
sessionId
Saves the open document. If a document is marked dirty, an error is returned
(a document is marked dirty when the server that opened the document has
become inactive; in such a case, the document must be closed and opened
again).
docName
newName
relativePath
String
String
String
String
Session in which the document
exists.
DescriptionTypeParameter
Document to be saved. Must be the
same name that was used when
opening or creating the document.
New name of the document. If null,
the document is saved with the old
name.
Relative path where the document
should be saved. The relative path
can also contain the new name of
the document. If this is provided, a
copy of the open document with
24 | QXP SERVER 9.2 WEB INTEGRATION GUIDE
GETTING STARTED
changes made so far is saved in the
new location. The open document
is not saved but has all of the
changes made so far.
JPEGRenderRequest jpegRequest = new JPEGRenderRequest();
rc.request = jpegRequest;
RequestService svc = new RequestService();
QContextData response = svc.processRequest(rc);
Base class for all request objects (such as PDFRenderRequest). All request objects share some common
data members, which are described below.
Web service data objectType
Lets you create a DOM of a particular layout or portion of a layout.
Creates an XML string out of the DOM.
Takes a raw XML representation of a project as a string and returns an object
model representing that project, with Project as the root class.
String
Session in which the document
exists.
Additional
comments
NameMembers
RequestParameters
Generic class for executing any request and for adding dynamic properties to a request.Description
Web service data objectType
NameMembers
requestNamespace
You can use this class to send any request for which a specific class does not exist. When this
request exists in the chain, its namespace is concatenated with the namespaces of other requests.
That means the namespace provided here can be null.
The parameters of this class can be used to parameterize a request being sent to the server.
DescriptionTypes
QRequestrequest
QuarkXPress Server request that includes instances of request objects
chained together.
DescriptionType
Namespace of the request (for example, jpeg).String
NameValueParam[]params
Parameter array for the specified request (for
example, jpegquality).
QXP SERVER 9.2 WEB INTEGRATION GUIDE | 25
GETTING STARTED
Example, object
model
NameValueParam
Description
QRequestContext rc = new QRequestContext();
RequestParameters request = new RequestParameters();
request.setRequestNamespace("jpeg");
rc.setRequest = request;
NameValueParam p1 = new NameValueParam();
p1.setParamName = "jpegquality";
p1.setTextValue = "4";
request.setParams(new NameValueParam[]{p1});
Generic class for adding dynamic properties to a request. This class is specifically for requests that take
a box name/id as the parameter name and the box content as the parameter value.
Web service data objectType
NameMembers
paramName
textValue
streamValue
String
String
byte[]
DescriptionType
Name of the parameter. In most cases this will be the name/ID of
the box.
Text value of the box. (You can set either textValue or
streamValue.)
Stream value of the box. (You can set either textValue or
streamValue.)
contentType
QContentData
A response to a Web Services call to QuarkXPress Server.Description
Web service data objectType
NameMembers
contentType
textData
responseURL
streamValue
encodingType
actualServerPortUsed
The MIME content type of the parameter.String
String
String
String
binary
String
DescriptionTypes
The type of the response. For example, "text/xml" or
"text/plain."
If the response type is text, this contains the text.
Otherwise, this value is null.
If the responseAsURL parameter was set to "true" in the
request, this contains the URL of the response.
Otherwise, this value is null.
If the response type is binary, this contains the byte
array. Otherwise, this value is null.
If the response type is text, this value indicates the
encoding of the text (for example, UTF-8 or ANSI).
Identifies the server port.String
actualServerUsed
26 | QXP SERVER 9.2 WEB INTEGRATION GUIDE
Identifies the server.String
GETTING STARTED
Example, object
model
QException
Type
headers
multipartResponse
QRequestContext context = new QRequestContext();
context.setDocumentName("sample.qxp");
context.setResponseAsURL(true);
JPEGRenderRequest request = new JPEGRenderRequest();
request.setJPEGQuality("4");
context.setRequest(request);
RequestService requestService = new RequestServiceStub();
QContentData response = requestService.processRequest(context);
System.out.println(response.getResponseURL());
Exception class for QuarkXPress Manager.Description
Exception
NameMembers
httpResponseCode
managerErrorCode
String
String
If the response returned by the server is a set of headers,
this array contains the header response.
If the response returned by the server is multipart, this
array contains the multipart response parts.
DescriptionTypes
HTTP response code.String
QuarkXPress Server Manager error code.String
Example,
object model
QXP Server Manager
managerErrorMessage
serverErrorCode
serverErrorMessage
serverExtendedMessage
String docName = "notexisting.qxp";
try {
QRequestContext ctx = getRequestContext(docName);
QRequest request = getJPEGRequest();
ctx.setRequest(ctx);
QContentData response = getService().processRequest(ctx);
System.out.println(response.getResponseURL());
} catch (QException ex) {
// QuarkXPress Manager threw an QException and it is not
// a runtime exception. QException object will be returned.
System.out.println(ex.getServerErrorCode());
}
QuarkXPress Server Manager localized error message.String
QuarkXPress Server error code.String
QuarkXPress Server response message.String
QuarkXPress Server extended error message.String
The following topics are for people who want to enhance QuarkXPress Server Manager or
integrate it with other software.
Please refer to http://localhost:8090/qxpsmdocs/apidocs/index.html for manager
API documentation. (Note that the port number used to retrieve the API documentation
QXP SERVER 9.2 WEB INTEGRATION GUIDE | 27
GETTING STARTED
is 8090 by default, but you should use whatever port number you specified when installing
QuarkXPress Server Manager.)
QuarkXPress Server Manager was developed using interface-based programming and uses
the Spring Framework to instantiate pluggable objects. When QuarkXPress Server Manager
starts up, it reads the contents of a Spring context definition file named
"ManagerContainerConfig.xml" and instantiates all of the beans listed in the file.
QuarkXPress Server Manager then initializes by reading various configuration options
from a file named "ManagerConfig.xml."
You can deploy QuarkXPress Server Manager in its own Tomcat container, in an external
Tomcat container, or in a shared Spring context. For more information, see "Deploying
QuarkXPress Server Manager" in the QuarkXPress Server ReadMe.
28 | QXP SERVER 9.2 WEB INTEGRATION GUIDE
Using the Web interface
The topics below describe the features available via the QuarkXPress Server Web interface.
The topics covered here include the following:
• Render types are namespaces you can use to return a QuarkXPress project in a specified file
format.
• Render modifiers let you control which parts of a project are rendered and set the scale of
the returned renderings.
USING THE WEB INTERFACE
• Content modifiers let you alter the content and formatting of boxes in layouts without using
the XML modify parameter.
• XML modify lets you modify QuarkXPress projects using XML.
•
The xml namespace deconstructs a project according to the Modifier DTD. The construct
namespace lets you turn an XML representation of a QuarkXPress project back into a
QuarkXPress project.
• Administrative request handlers let you change the behavior of QuarkXPress Server.
QuarkXPress Server uses case-sensitive XML.
Understanding rendering
Rendering is the process in which QuarkXPress Server opens a QuarkXPress project,
transforms it into a different format (the render type), and then sends a response to the
requestor. Depending on the type of rendering operation, the response may be a message
or a rendered file.
For information on how to submit a render request, see "Getting started: HTTP and HTTPS."
Alerts
document type.
Please select a
QuarkXPress
document or
template.
HTTP Error #500Cannot open this
This alert displays if you try to render a file that is not a QuarkXPress project.
QXP SERVER 9.2 WEB INTEGRATION GUIDE | 29
USING THE WEB INTERFACE
read or write to disk.
required volume or
folder.
HTTP Error #404File not found
QuarkXPress Server Error #–43
This alert displays if you try to render a project that does not exist.
HTTP Error #500I/O error trying to
QuarkXPress Server Error #–36
This alert displays if QuarkXPress Server is running on Windows and a shared
network folder was selected as the document pool, but the folder is no longer
shared.
What to do: In the QuarkXPress Server administration interface, choose
Administration > Preferences > General and set Document Root Folder
to a shared folder.
HTTP Error #404Cannot find
QuarkXPress Server Error #–35
This alert displays if QuarkXPress Server is running on Mac OS and a shared
network volume was selected as the document pool, but the volume is no
longer shared.
What to do: In the QuarkXPress Server administration interface, choose
Administration > Preferences > General and set Document Root Folder
to a shared folder.
Example, GET
URL
Understanding logging
If a request succeeds, a transaction success message is written to the QuarkXPress Server
transaction log file. This message includes the transaction ID, date, time, request type,
project name, response type, response size in bytes, and client IP address. For example:
If an alert is displayed, an error message is written to the QuarkXPress Server transaction
log file. The transaction entry contains the date and time of the request, the error code,
and the error message. The following is a sample of an error log transaction entry:
See Understanding loggingLogs
http://localhost:8080/sample.qxp
There are two ways to specify a render format:Notes
1. Enter the render type directly in the browser address
field:http://localhost:8080/pdf/project.qxp.
2. In the QuarkXPress Server administration interface, choose Administration > Preferences >General and choose the default render type from the Default Renderer Type drop-down menu.
09/03/2011 13:54:33 - RequestURI = /sample.qcd TransactionUUID =
dffc3a7e-11fd-4d97-b3fe-8f2129353d58 Client = 10.91.30.216 Error #10120 Cannot open this document type. Please select a QuarkXPress document or template.
30 | QXP SERVER 9.2 WEB INTEGRATION GUIDE
Loading...
+ 239 hidden pages
You need points to download manuals.
1 point = 1 manual.
You can buy points or you can get point for every manual you upload.