|
Typically, a form design that is created in Designer is
passed by reference to the Forms service. Form designs can be large
and, as a result, it is more efficient to pass them by reference
to avoid having to marshal form design bytes by value. The Forms
service can also cache the form design so that when cached, it does
not have to continually read the form design.
If a form design contains a UUID attribute, then it is cached.
The UUID value is unique for all form designs and is used to uniquely
identify a form. When rendering a form by value, the form should
only be cached when it is used repeatedly. However, if the form
is not used repeatedly and has to be unique, you can avoid caching
the form using caching options that are set using the LiveCycle API.
The Forms service can also resolve the location of linked content
within the form design. For example, linked images that are referenced
from within the form design are relative URLs. Linked content is
always assumed to be relative to the form design location. Therefore,
resolving linked content is a matter of determining its location
by applying the relative path to the absolute form design location.
Instead of passing a form design by reference, you can pass a
form design by value. Passing a form design by value is efficient
when a form design is dynamically created; that is, when a client
application generates the XML that creates a form design during
run-time. In this situation a form design is not stored in a physical
repository because it is stored in memory. When dynamically creating
a form design at run-time and passing it by value, you can cache
the form and improve performance of the Forms service.
Limitations of passing a form by valueThe following limitations apply
when a form design is passed by value:
No relative
linked content can be within the form design. All images and fragments
must be embedded inside the form design or referred to absolutely.
Server-side calculations cannot be performed after the form
is rendered. If the form is submitted back to the Forms service,
the data is extracted and returned without any server-side calculations.
Because HTML can only use linked images at run time, it is
not possible to generate HTML with embedded images. This is because
the Forms service supports embedded images with HTML by retrieving
the images from a referenced form design. Because a form design
that is passed by value does not have a referenced location, embedded
images cannot be extracted when the HTML page is displayed. Therefore,
image references must be absolute paths to be rendered in HTML.
Hinweis: Although you can render different types of forms
by value (for example, HTML forms or forms that contain usage rights),
this section discusses rendering interactive PDF forms.
Summary of stepsTo
render a form by value, perform the following steps:
Include project files.
Create a Forms Client API object.
Reference the form design.
Render a form by value.
Write the form data stream to the client web browser.
Include project filesInclude necessary files into your development
project. If you are creating a client application using Java, then
include the necessary JAR files. If you are using web services,
then make sure that you include the proxy files.
Create a Forms Client API objectBefore you can programmatically
import data into a PDF form Client API, you must create a Data Integration
service client. When creating a service client, you define connection
settings that are required to invoke a service.
Reference the form designWhen rendering a form by value, you have
to create a com.adobe.idp.Document object that
contains the form design to render. You can reference an existing
XDP file or you can dynamically create an form design at run-time
and populate a com.adobe.idp.Document with that
data.
Hinweis: This section and the corresponding
quick start references an existing XDP file.
Render a form by valueTo render a form by value, pass a com.adobe.idp.Document instance
that contains the form design to the render method’s inDataDoc parameter
(can be any of the FormsServiceClient object’s
render methods such as renderPDFForm, renderHTMLForm,
and so on). This parameter value is normally reserved for data that
is merged with the form. Likewise, pass an empty string value to
the formQuery parameter. Normally this parameter
requires a string value that specifies the name of the form design.
Write the form data stream to the client web browserWhen the
Forms service renders a form by value, it returns a form data stream
that you must write to the client web browser. When written to the
client web browser, the form is visible to the user.
Render a form by value using the Java APIRender a form by value using the Forms API
(Java):
Include project files
Include client JAR files,
such as adobe-forms-client.jar, in your Java project’s class path.
Create a Forms Client API object
Reference the form design
Create a java.io.FileInputStream object
that represents the form design to render by using its constructor
and passing a string value that specifies the location of the XDP
file.
Create a com.adobe.idp.Document object by
using its constructor and passing the java.io.FileInputStream object.
Render a form by value
Invoke the FormsServiceClient object’s renderPDFForm method
and pass the following values:
An empty string value.
(Normally this parameter requires a string value that specifies
the name of the form design.)
A com.adobe.idp.Document object that contains
the form design. Normally this parameter value is reserved for data
that is merged with the form.
A PDFFormRenderSpec object that stores run-time
options. This is an optional parameter and you can specify null if
you do not want to specify run-time options.
A URLSpec object that contains URI values that
are required by the Forms service.
A java.util.HashMap object that stores file
attachments. This is an optional parameter and you can specify null if
you do not want to attach files to the form.
The renderPDFForm method
returns a FormsResult object that contains a form
data stream that can be written to the client web browser.
Write the form data stream to the client web browser
Create a com.adobe.idp.Document object by
invoking the FormsResult object ‘s getOutputContent method.
Get the content type of the com.adobe.idp.Document object
by invoking its getContentType method.
Set the javax.servlet.http.HttpServletResponse object’s
content type by invoking its setContentType method
and passing the content type of the com.adobe.idp.Document object.
Create a javax.servlet.ServletOutputStream object
used to write the form data stream to the client web browser by invoking
the javax.servlet.http.HttpServletResponse object’s getOutputStream method.
Create a java.io.InputStream object by invoking
the com.adobe.idp.Document object’s getInputStream method.
Create a byte array and allocate the size of the InputStream object.
Invoke the InputStream object’s available method
to obtain the size of the InputStream object.
Populate the byte array with the form data stream by invoking
the InputStream object’s read method
and passing the byte array as an argument.
Invoke the javax.servlet.ServletOutputStream object’s write method
to send the form data stream to the client web browser. Pass the
byte array to the write method.
Render a form by value using the web service APIRender a form by value by using the Forms API (web service):
Include project files
Create a Forms Client API object
Create a FormsService object
and set authentication values.
Reference the form design
Create a java.io.FileInputStream object
by using its constructor. Pass a string value that specifies the
location of the XDP file.
Create a BLOB object by using its constructor.
The BLOB object is used to store a PDF document
that is encrypted with a password.
Create a byte array that stores the content of the java.io.FileInputStream object.
You can determine the size of the byte array by getting the java.io.FileInputStream object’s
size using its available method.
Populate the byte array with stream data by invoking the java.io.FileInputStream object’s read method
and passing the byte array.
Populate the BLOB object by invoking its setBinaryData method
and passing the byte array.
Render a form by value
Invoke the FormsService object’s renderPDFForm method
and pass the following values:
An empty string value.
(Normally this parameter requires a string value that specifies
the name of the form design.)
A BLOB object that contains the form design.
Normally this parameter value is reserved for data that is merged with
the form.
A PDFFormRenderSpec object that stores run-time
options. This is an optional parameter and you can specify null if
you do not want to specify run-time options.
A URLSpec object that contains URI values that
are required by the Forms service.
A java.util.HashMap object that stores file
attachments. This is an optional parameter and you can specify null if
you do not want to attach files to the form.
An empty com.adobe.idp.services.holders.BLOBHolder object
that is populated by the method. This is used to store the rendered
PDF form.
An empty javax.xml.rpc.holders.LongHolder object that
is populated by the method. (This argument stores the number of pages
in the form.)
An empty javax.xml.rpc.holders.StringHolder object
that is populated by the method. (This argument stores the locale value.)
An empty com.adobe.idp.services.holders.FormsResultHolder object
that will contain the results of this operation.
The renderPDFForm method
populates the com.adobe.idp.services.holders.FormsResultHolder object
that is passed as the last argument value with a form data stream
that must be written to the client web browser.
Write the form data stream to the client web browser
Create a FormResult object by getting the
value of the com.adobe.idp.services.holders.FormsResultHolder object’s value data
member.
Create a BLOB object that contains form data
by invoking the FormsResult object’s getOutputContent method.
Get the content type of the BLOB object
by invoking its getContentType method.
Set the javax.servlet.http.HttpServletResponse object’s
content type by invoking its setContentType method
and passing the content type of the BLOB object.
Create a javax.servlet.ServletOutputStream object
used to write the form data stream to the client web browser by invoking
the javax.servlet.http.HttpServletResponse object’s getOutputStream method.
Create a byte array and populate it by invoking the BLOB object’s getBinaryData method.
This task assigns the content of the FormsResult object
to the byte array.
Invoke the javax.servlet.http.HttpServletResponse object’s write method
to send the form data stream to the client web browser. Pass the
byte array to the write method.
|
|
|
