Overview  Package   Class  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.adobe.livecycle.formsservice.client
Class FormsServiceClient

java.lang.Object
  extended by com.adobe.livecycle.formsservice.client.FormsServiceClient

public class FormsServiceClient
extends java.lang.Object

Allows you to create a Java object that invokes operations that belong to the Forms service. Using this object, you can perform tasks such as rendering forms to client devices, (typically web browsers), to collect information from end users. After a form is rendered, the user can fill in the form and send information back to the Forms service by clicking a submit button located on the form. You can also use a FormsServiceClient object to process a submitted form. To see an object of this type used in a code example, see the Rendering an interactive PDF form using the Java API quick start in Programming with LiveCycle ES4.

Constructor Summary
FormsServiceClient(ServiceClientFactory serviceClientFactory)
          A constructor that creates a FormsServiceClient object.
 
Method Summary
 void addDocument(Document oDoc, java.lang.String displayName)
          Adds a file attachment to the form design that is rendered.
 java.util.ArrayList getDocuments()
          Returns a list of all file attachments that were attached to the form.
 FormsResult processFormSubmission(Document inRequestDoc, java.lang.String environmentBuffer, java.lang.String userAgent, RenderOptionsSpec processFormSubmissionOptionsSpec)
          Processes the posted content from a client device (typically, a web browser) and returns the results.
 void removeDocument(java.lang.String name)
          Removes a file attachment from the form.
 FormsResult renderFormGuide(java.lang.String formQuery, Document inDataDoc, PDFFormRenderSpec pdfFormRenderSpec, ActivityGuideRenderSpec activityGuideRenderSpec, URLSpec urlSpec)
          Renders a form guide to a client device.
 FormsResult renderHTMLForm(java.lang.String formQuery, TransformTo transformTo, Document inDataDoc, HTMLRenderSpec htmlRenderSpec, java.lang.String userAgent, URLSpec urlSpec, java.util.Map attachments)
          Renders an HTML form to a client device by retrieving the specified form design and transforming it to an HTML form as specified by the transformTo value.
 FormsResult renderHTMLForm2(Document inFormDoc, TransformTo transformTo, Document inDataDoc, HTMLRenderSpec htmlRenderSpec, java.lang.String userAgent, URLSpec urlSpec, java.util.Map attachments)
          Renders an HTML form to a client device by retrieving the specified form design and transforming it to an HTML form as specified by the transformTo value.
 FormsResult renderPDFForm(java.lang.String formQuery, Document inDataDoc, PDFFormRenderSpec pdfFormRenderSpec, URLSpec urlSpec, java.util.Map attachments)
          Renders a PDF form to a client device by retrieving the specified form design and transforming it to a PDF form.
 FormsResult renderPDFForm2(Document inFormDoc, Document inDataDoc, PDFFormRenderSpec pdfFormRenderSpec, URLSpec urlSpec, java.util.Map attachments)
          Renders a PDF form to a client device by retrieving the specified form design and transforming it to a PDF form.
 FormsResult renderPDFFormWithUsageRights(java.lang.String formQuery, Document inDataDoc, PDFFormRenderSpec pdfFormRenderSpec, ReaderExtensionSpec readerExtensionSpec, URLSpec urlSpec)
          Renders a rights-enabled PDF form to a client device.
 void resetCache()
          Exposes the reset cache functionality for Forms Administrator as an API operation.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

FormsServiceClient

public FormsServiceClient(ServiceClientFactory serviceClientFactory)
A constructor that creates a FormsServiceClient object.

Parameters:
serviceClientFactory - A ServiceClientFactory object that contains connection properties. For information about setting connection properties, see the Setting connection properties topic in Programming with LiveCycle ES4.
Method Detail

renderHTMLForm

public FormsResult renderHTMLForm(java.lang.String formQuery,
                                  TransformTo transformTo,
                                  Document inDataDoc,
                                  HTMLRenderSpec htmlRenderSpec,
                                  java.lang.String userAgent,
                                  URLSpec urlSpec,
                                  java.util.Map attachments)
                           throws RenderFormException,
                                  com.adobe.idp.dsc.DSCException
Renders an HTML form to a client device by retrieving the specified form design and transforming it to an HTML form as specified by the transformTo value. When invoking this method, a form design is referenced by a URI value. The results are returned in a FormsResult object.

To see this method used in a code example, see the Rendering an HTML form using the Java API quick start in Programming with LiveCycle ES4.

Parameters:
formQuery - The name of the form design to render. This parameter references a form design that is saved as an XDP. You cannot use a PDF file to render an HTML form. The form design is typically created in Adobe LiveCycle Designer. For information, see the LiveCycle Designer Help.
transformTo - A TransformTo enum value that specifies the type of HTML form to render. For example, TransformTo.MSDHTML renders a dynamic HTML form for Internet Explorer 5.0 or later.
inDataDoc - A com.adobe.idp.Document object representing data to merge with the form design during rendering.
htmlRenderSpec - A HTMLRenderSpec object that represents run-time options that are used when rendering an HTML form.
userAgent - The HTTP_USER_AGENT header that provides information about the target device. This parameter is used when formPreference is set to AUTO. The default is Mozilla/3.*.
urlSpec - A URLSpec object that represents URI values that are required by the Forms service while rendering a form. This object defines URI values such as the location of the form design and the URI location to where form data is posted.
attachments - A java.util.Map object that contains file attachments that are rendered with the form. This Map object requires a name-value pair where the name is a string value that represents the file name and the value is a com.adobe.idp.Document object that contains file data.
Returns:
A FormsResult object containing the results of the request. Using this object, you can perform tasks, such as writing a data stream that represents the HTML form, to a client web browser.
Throws:
RenderFormException
com.adobe.idp.dsc.DSCException

renderHTMLForm2

public FormsResult renderHTMLForm2(Document inFormDoc,
                                   TransformTo transformTo,
                                   Document inDataDoc,
                                   HTMLRenderSpec htmlRenderSpec,
                                   java.lang.String userAgent,
                                   URLSpec urlSpec,
                                   java.util.Map attachments)
                            throws RenderFormException,
                                   com.adobe.idp.dsc.DSCException
Renders an HTML form to a client device by retrieving the specified form design and transforming it to an HTML form as specified by the transformTo value. The results are returned in a FormsResult object. When invoking this method, a form design is passed to the Forms service within a com.adobe.idp.Document object. This method was added in LiveCycle ES2.

Parameters:
inFormDoc - A com.adobe.idp.Document object representing the form design to render. The form design is typically created in Adobe LiveCycle Designer. For information, see the LiveCycle Designer ES Help.
transformTo - A TransformTo enum value that specifies the type of HTML form to render. For example, TransformTo.MSDHTML renders a dynamic HTML form for Internet Explorer 5.0 or later.
inDataDoc - A com.adobe.idp.Document object representing data to merge with the form design during rendering.
htmlRenderSpec - A HTMLRenderSpec object that represents run-time options that are used when rendering an HTML form.
userAgent - The HTTP_USER_AGENT header that provides information about the target device. This parameter is used when formPreference is set to AUTO. The default is Mozilla/3.*.
urlSpec - A URLSpec object that represents URI values that are required by the Forms service while rendering a form. When invoking this method, you do not have to use this parameter value to specify the location of the form design. The form design is passed within a com.adobe.idp.Document object as the inFormDoc parameter.
attachments - A java.util.Map object that contains file attachments that are rendered with the form. This Map object requires a name-value pair where the name is a string value that represents the file name and the value is a com.adobe.idp.Document object that contains file data.
Returns:
A FormsResult object containing the results of the request. Using this object, you can perform tasks, such as writing a data stream that represents the HTML form, to a client web browser.
Throws:
RenderFormException
com.adobe.idp.dsc.DSCException

renderPDFForm

public FormsResult renderPDFForm(java.lang.String formQuery,
                                 Document inDataDoc,
                                 PDFFormRenderSpec pdfFormRenderSpec,
                                 URLSpec urlSpec,
                                 java.util.Map attachments)
                          throws RenderFormException,
                                 com.adobe.idp.dsc.DSCException
Renders a PDF form to a client device by retrieving the specified form design and transforming it to a PDF form. When invoking this method, a form design is referenced by a URI value. The results are returned in a FormsResult object.

To see this method used in a code example, see the Rendering an interactive PDF form using the Java API quick start in Programming with LiveCycle ES4.

Parameters:
formQuery - The name of the form design or PDF document to render. This parameter references a form design that is saved as either an XDP or a PDF file. The form design is typically created in Adobe LiveCycle Designer. For information, see the LiveCycle Designer Help.
inDataDoc - A com.adobe.idp.Document object representing data to merge with the form design during rendering.
pdfFormRenderSpec - A PDFFormRenderSpec object that represents run-time options that are used when rendering a PDF form.
urlSpec - A URLSpec object that represents URI values that are required by the Forms service while rendering a form. This object defines URI values such as the location of the form design and the URI location to where form data is posted.
attachments - A java.util.Map object that contains file attachments that are rendered with the form. This Map object requires a name-value pair where the name is a string value that represents the file name and the value is a com.adobe.idp.Document object that contains file data.
Returns:
A FormsResult object containing the results of the request. Using this object, you can perform tasks, such as writing a data stream that represents the form, to a client web browser.
Throws:
RenderFormException
com.adobe.idp.dsc.DSCException

renderPDFForm2

public FormsResult renderPDFForm2(Document inFormDoc,
                                  Document inDataDoc,
                                  PDFFormRenderSpec pdfFormRenderSpec,
                                  URLSpec urlSpec,
                                  java.util.Map attachments)
                           throws RenderFormException,
                                  com.adobe.idp.dsc.DSCException
Renders a PDF form to a client device by retrieving the specified form design and transforming it to a PDF form. When invoking this method, a form design is passed to the Forms service within a com.adobe.idp.Document object. The results are returned in a FormsResult object. This method was added in LiveCycle ES2.

To see this method used in a code example, see the Passing Documents to the Forms Service quick start in Programming with LiveCycle ES4.

Parameters:
inFormDoc - A com.adobe.idp.Document object representing the form design to render. The form design is typically created in Adobe LiveCycle Designer ES2. For information, see LiveCycle Designer ES2 Help.
inDataDoc - A com.adobe.idp.Document object representing form data to merge with the form design during rendering.
pdfFormRenderSpec - A PDFFormRenderSpec object that represents run-time options that are used when rendering a PDF form.
urlSpec - A URLSpec object that represents URI values that are required by the Forms service while rendering a form. When invoking this method, you do not have to use this parameter value to specify the location of the form design. The form design is passed within a com.adobe.idp.Document object as the inFormDoc parameter.
attachments - A java.util.Map object that contains file attachments that are rendered with the form. This Map object requires a name-value pair where the name is a string value that represents the file name and the value is a com.adobe.idp.Document object that contains file data.
Returns:
A FormsResult object containing the results of the request. Using this object, you can perform tasks, such as writing a data stream that represents the form, to a client web browser.
Throws:
RenderFormException
com.adobe.idp.dsc.DSCException

renderPDFFormWithUsageRights

public FormsResult renderPDFFormWithUsageRights(java.lang.String formQuery,
                                                Document inDataDoc,
                                                PDFFormRenderSpec pdfFormRenderSpec,
                                                ReaderExtensionSpec readerExtensionSpec,
                                                URLSpec urlSpec)
                                         throws RenderFormException,
                                                com.adobe.idp.dsc.DSCException
Renders a rights-enabled PDF form to a client device. Usage rights pertain to functionality that is available by default in Acrobat but not in Adobe Reader, such as the ability to add comments to a form or to fill in form fields and save the form. A PDF form that has usage rights applied to it is called a rights-enabled form. The results are returned in a FormsResult object.

To see this method used in a code example, see the Rendering a rights-enabled form using the Java API quick start in Programming with LiveCycle ES4.

Parameters:
formQuery - The name of the form design or PDF document to render. This parameter references a form design that is saved as either an XDP or a PDF file. The form design is typically created in Designer ES2. For information, see the LiveCycle Designer Help.
inDataDoc - A com.adobe.idp.Document object representing data to merge with the form design during rendering.
pdfFormRenderSpec - A PDFFormRenderSpec object that represents run-time options that are used when rendering a PDF form.
readerExtensionSpec - A ReaderExtensionSpec object that represents run-time options that are required to render a rights-enabled form.
urlSpec - A URLSpec object that represents URI values that are required by the Forms service while rendering a form. This object defines URI values such as the location of the form design and the URI location to where form data is posted. requires a name-value pair where the name is a string value that represents the file name and the value is a com.adobe.idp.Document object that contains file data.
Returns:
A FormsResult object containing the results of the request. Using this object, you can perform tasks, such as writing a data stream that represents the form, to a client web browser. For information, see "Rendering Rights-Enabled Forms" in Programming with LiveCycle ES4.
Throws:
RenderFormException
com.adobe.idp.dsc.DSCException

renderFormGuide

public FormsResult renderFormGuide(java.lang.String formQuery,
                                   Document inDataDoc,
                                   PDFFormRenderSpec pdfFormRenderSpec,
                                   ActivityGuideRenderSpec activityGuideRenderSpec,
                                   URLSpec urlSpec)
                            throws RenderFormException,
                                   com.adobe.idp.dsc.DSCException
Renders a form guide to a client device. Form guides are Adobe Flash-based representations of a form design that provide a more visually engaging and streamlined method for capturing data during form filling. This can help reduce data entry errors through improved usability by simplifying the amount of information presented to a user at a given time. The results are returned in a FormsResult object.

To see this method used in a code example, see the Rendering a form guide using the Java API quick start in Programming with LiveCycle ES4.

Parameters:
formQuery - The name of the form design or PDF document to render. This parameter references a form design that is saved as either an XDP or a PDF file. The form design is typically created in Adobe LiveCycle Designer. For information, see the LiveCycle Designer Help.
inDataDoc - A com.adobe.idp.Document object representing data to merge with the form design during rendering.
pdfFormRenderSpec - A PDFFormRenderSpec object that represents run-time options that are used when rendering a PDF form.
activityGuideRenderSpec - An ActivityGuideRenderSpec object that represents run-time options that are required to render a form guide.
urlSpec - A URLSpec object that represents URI values that are required by the Forms service while rendering a form. This object defines URI values such as the location of the form design and the URI location to where form data is posted.
Returns:
A FormsResult object containing the results of the request. Using this object, you can perform tasks, such as writing a data stream that represents the form, to a client web browser. For information, see "Rendering Form Guides" in Programming with LiveCycle ES4.
Throws:
RenderFormException
com.adobe.idp.dsc.DSCException

processFormSubmission

public FormsResult processFormSubmission(Document inRequestDoc,
                                         java.lang.String environmentBuffer,
                                         java.lang.String userAgent,
                                         RenderOptionsSpec processFormSubmissionOptionsSpec)
                                  throws ProcessFormSubmissionException,
                                         com.adobe.idp.dsc.DSCException
Processes the posted content from a client device (typically, a web browser) and returns the results. The results are either content that is written to the client application or validated XML data. The getAction method, which belongs to the FormsResult object, specifies the type of action that the Form service performed. For example, if the action indicates that the Form service is finished processing data, then the result is either validated XML data or PDF data. If the action is not complete, the results are returned to the client device. For example, if the Forms service performs a calculation on data values, the result is sent back to a web browser where it is displayed. For information about handling calculations, see the Calculating Form Data topic in Programming with LiveCycle ES4.

If the content type of the data passed to this method is not a supported type, this method returns the data, including the unsupported content type, without processing it. For information about processing a submitted form, see the Handling Submitted Forms topic in Programming with LiveCycle ES4.

To see this method used in a code example, see either the Handling forms submitted as XML using the Java API quick start or Handling forms submitted as PDF using the Java API quick start in Programming with LiveCycle ES4.

Parameters:
inRequestDoc - A com.adobe.idp.Document object that represents the posted content. From within a Java servlet, you can create a com.adobe.idp.Document object by invoking the HttpServletRequest object's getInputStream method: Document myDocument = new Document(req.getInputStream());
environmentBuffer - Specifies environment variables included all relevant HTTP headers. The following format is valid: HTTP_REFERER=referrer&HTTP_CONNECTION=keep-alive. If you want to set your own environment variables, you must assign values to these variables:
  • HTTP_USER_AGENT
  • CONTENT_TYPE
  • CONTENT_LENGTH
    • In this situation, other environment variables, such as HTTP_CONNECTION, use default values. In addition to setting the required variables previously specified, you can override an environment variable's default value by assigning a new value. The CONTENT_TYPE variable accepts the following content types:
  • text/xml
  • application/xml
  • application/vnd.adobe.xdp
    • userAgent - The HTTP header User-Agent that provides information about the target device (a target device is a client application, such as a web browser). This value takes precedence over what may exist in environment variables. The default value is Mozilla/3.*.
    processFormSubmissionOptionsSpec - A RenderOptionsSpec object that represents run-time options that are used when a form is processed.
    Returns:
    A FormsResult object containing the results of the form submission.
    Throws:
    ProcessFormSubmissionException - If an error occurs such as an invalid value for the inRequestDoc parameter.
    com.adobe.idp.dsc.DSCException

    addDocument

    public void addDocument(Document oDoc,
                        java.lang.String displayName)
    Adds a file attachment to the form design that is rendered. For information about adding a file attachment, see the "Rendering Interactive PDF Forms" section in Programming with LiveCycle ES4.

    To see this method used in a code example, see the Rendering an interactive PDF form using the Java API quick start in Programming with LiveCycle ES4.

    Parameters:
    oDoc - A com.adobe.idp.Document object that contains a file that is added as a file attachment.
    displayName - The name of the file attachment. This value is used as the name of the link that is used to download this file attachment.

    removeDocument

    public void removeDocument(java.lang.String name)
    Removes a file attachment from the form.

    Parameters:
    name - A string value that represents the file attachment to remove from the form.

    resetCache

    public void resetCache()
                throws FormServerException,
                       com.adobe.idp.dsc.DSCException
    Exposes the reset cache functionality for Forms Administrator as an API operation. This method deletes all the cached entries from the Disk and In-Memory Caches used by Forms Service. This API can only be accessed by a user having a PERM_FORMS_ADMIN permission. This method was added in LiveCycle ES2.

    Throws:
    FormServerException - Contains the root exception.
    com.adobe.idp.dsc.DSCException

    getDocuments

    public java.util.ArrayList getDocuments()
    Returns a list of all file attachments that were attached to the form. You can retrieve file attachments from the java.util.ArrayList object that is returned by this method. File attachments can be added by using the addDocument method. You can only retrieve file attachments from a form if the form was submitted as PDF data.

    Returns:
    A java.util.ArrayList object that contains file attachments.
    See Also:
    (Document, String)
    Overview  Package   Class  Tree  Deprecated  Index  Help 
     PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
    SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
    [an error occurred while processing this directive] [an error occurred while processing this directive]