文件 AEM 6.5 使用手冊

使用Java API叫用AEM Forms

最後更新： 2024年7月14日

適用對象：
Experience Manager 6.5

主題：

建立對象：

開發人員

本檔案中的範例和範例僅適用於JEE環境上的AEM Forms。

AEM Forms可透過使用AEM Forms Java API來叫用。使用AEM Forms Java API時，您可以使用叫用API或Java使用者端資料庫。 Java使用者端程式庫可用於Rights Management服務之類的服務。這些強型別API可讓您開發叫用AEM Forms的Java應用程式。

引動API是com.adobe.idp.dsc封裝中的類別。使用這些類別，您可以直接傳送呼叫要求給服務，並處理傳回的呼叫回應。使用叫用API來叫用使用Workbench建立的短期或長期程式。

以程式設計方式叫用服務的建議方法是使用與服務相對應的Java使用者端程式庫，而不是叫用API。例如，若要叫用加密服務，請使用加密服務使用者端程式庫。若要執行「加密」服務作業，請叫用屬於「加密」服務使用者端物件的方法。您可以叫用EncryptionServiceClient物件的encryptPDFUsingPassword方法，以密碼加密PDF檔案。

Java API支援下列功能：

遠端呼叫的RMI傳輸通訊協定
本機呼叫的VM傳輸
用於遠端呼叫的SOAP
不同的驗證，例如使用者名稱和密碼
同步和非同步呼叫要求

包含AEM Forms Java程式庫檔案

叫用以人為中心的長期流程

使用網站服務叫用AEM Forms

設定連線屬性

使用Java API傳遞資料至AEM Forms服務

使用Java使用者端程式庫叫用服務

使用叫用API叫用短期程式

建立可叫用以人為中心的長期流程的Java網頁應用程式

包含AEM Forms Java程式庫檔案

若要使用Java API以程式設計方式叫用AEM Forms服務，請在Java專案的類別路徑中加入必要的程式庫檔案（JAR檔案）。包含在使用者端應用程式類別路徑中的JAR檔案取決於幾個因素：

要呼叫的AEM Forms服務。使用者端應用程式可以叫用一或多個服務。
您要叫用AEM Forms服務的模式。您可以使用EJB或SOAP模式。（請參閱設定連線屬性。）

NOTE

（僅全包式）使用命令standalone.bat -b <Server IP> -c lc_turnkey.xml啟動AEM Forms伺服器，以指定EJB的伺服器IP

部署AEM Forms的J2EE應用程式伺服器。

服務特定的JAR檔案

下表列出呼叫AEM Forms服務所需的JAR檔案。

檔案

說明

位置

adobe-livecycle-client.jar

必須一律包含在Java使用者端應用程式的類別路徑中。

<安裝目錄>/sdk/client-libs/common

adobe-usermanager-client.jar

必須一律包含在Java使用者端應用程式的類別路徑中。

<安裝目錄>/sdk/client-libs/common

adobe-utilities.jar

必須一律包含在Java使用者端應用程式的類別路徑中。

<安裝目錄>/sdk//client-libs/<應用程式伺服器>

adobe-applicationmanager-client-sdk.jar

呼叫Application Manager服務時需要。

<安裝目錄>/sdk/client-libs/common

adobe-assembler-client.jar

需要才能叫用Assembler服務。

<安裝目錄>/sdk/client-libs/common

adobe-backup-restore-client-sdk.jar

呼叫備份和還原服務API時需要。

<安裝目錄>/sdk/client-libs/common

adobe-barcodedforms-client.jar

呼叫條碼式表單服務時需要。

<安裝目錄>/sdk/client-libs/common

adobe-convertpdf-client.jar

呼叫轉換PDF服務時需要。

<安裝目錄>/sdk/client-libs/common

adobe-distiller-client.jar

呼叫Distiller服務時需要。

<安裝目錄>/sdk/client-libs/common

adobe-docconverter-client.jar

呼叫DocConverter服務時需要。

<安裝目錄>/sdk/client-libs/common

adobe-contentservices-client.jar

呼叫Document Management服務時需要。

<安裝目錄>/sdk/client-libs/common

adobe-encryption-client.jar

需要才能叫用加密服務。

<安裝目錄>/sdk/client-libs/common

adobe-forms-client.jar

呼叫Forms服務時需要。

<安裝目錄>/sdk/client-libs/common

adobe-formdataintegration-client.jar

呼叫表單資料整合服務時需要。

<安裝目錄>/sdk/client-libs/common

adobe-generatepdf-client.jar

呼叫產生PDF服務時需要。

<安裝目錄>/sdk/client-libs/common

adobe-generate3dpdf-client.jar

必須呼叫「產生3DPDF」服務。

<安裝目錄>/sdk/client-libs/common

adobe-jobmanager-client-sdk.jar

呼叫「工作管理員」服務時需要。

<安裝目錄>/sdk/client-libs/common

adobe-output-client.jar

需要才能叫用Output服務。

<安裝目錄>/sdk/client-libs/common

adobe-pdfutility-client.jar

呼叫「PDF公用程式」或「XMP公用程式」服務時需要。

<安裝目錄>/sdk/client-libs/common

adobe-reader-extensions-client.jar

呼叫Acrobat Reader DC擴充功能服務時需要。

<安裝目錄>/sdk/client-libs/common

adobe-repository-client.jar

commons-codec-1.3.jar

呼叫存放庫服務時需要。

<安裝目錄>/sdk/client-libs/common

<安裝目錄>/sdk/client-libs\thirdparty

adobe-rightsmanagement-client.jar
namespace.jar
jaxb-api.jar
jaxb-impl.jar
jaxb-libs.jar
jaxb-xjc.jar
relaxngDatatype.jar
xsdlib.jar

呼叫Rights Management服務時需要。

如果AEM Forms部署在JBoss上，請包含所有這些檔案。

<安裝目錄>/sdk/client-libs/common

JBoss專屬程式庫目錄

adobe-signatures-client.jar

需要才能叫用簽名服務。

<安裝目錄>/sdk/client-libs/common

adobe-taskmanager-client-sdk.jar

呼叫Task Manager服務時需要。

<安裝目錄>/sdk/client-libs/common

adobe-truststore-client.jar

必須呼叫信任存放區服務。

<安裝目錄>/sdk/client-libs/common

連線模式和J2EE應用程式JAR檔案

下表列出的JAR檔案，視連線模式以及部署AEM Forms的J2EE應用程式伺服器而定。

檔案

說明

位置

activation.jar
axis.jar
commons-codec-1.3.jar
commons-collections-3.1.jar
commons-discovery.jar
commons-logging.jar
dom3-xml-apis-2.5.0.jar
jaxen-1.1-beta-9.jar
jaxrpc.jar
log4j.jar
mail.jar
saaj.jar
wsdl4j.jar
xalan.jar
xbean.jar

xercesImpl.jar
commons-httpclient-3.1.jar

如果使用SOAP模式叫用AEM Forms，請包含這些JAR檔案。

<安裝目錄>/sdk/client-libs/thirdparty

jboss-client.jar

如果AEM Forms部署在JBoss Application Server上，請包含此JAR檔案。

如果jboss-client.jar和參照的jar不在同一位置，則類別載入器找不到所需的類別。

JBoss使用者端程式庫目錄

如果您將使用者端應用程式部署在同一J2EE應用程式伺服器上，則不需要包含此檔案。

wlclient.jar

如果AEM Forms部署在BEA WebLogic Server®上，則包含此JAR檔案。

WebLogic專屬程式庫目錄

如果您將使用者端應用程式部署在同一J2EE應用程式伺服器上，則不需要包含此檔案。

com.ibm.ws.admin.client_6.1.0.jar
com.ibm.ws.webservices.thinclient_6.1.0.jar

如果AEM Forms部署在WebSphere Application Server上，請包含這些JAR檔案。
(Web服務呼叫需要com.ibm.ws.webservices.thinclient_6.1.0.jar)。

WebSphere特定的lib目錄([WAS_HOME]/runtime)

如果您將使用者端應用程式部署在同一J2EE應用程式伺服器上，則不需要包含這些檔案。

叫用案例

下表指定叫用案例，並列出成功叫用AEM Forms所需的JAR檔案。

服務

叫用模式

J2EE應用程式伺服器

必要的JAR檔案

Forms服務

EJB

Jboss

adobe-livecycle-client.jar
adobe-usermanager-client.jar

jboss-client.jar

adobe-forms-client.jar
commons-httpclient-3.1.jar

Forms服務

Acrobat Reader DC擴充功能服務

簽章服務

EJB

Jboss

adobe-livecycle-client.jar
adobe-usermanager-client.jar

jboss-client.jar
commons-httpclient-3.1.jar

adobe-forms-client.jar
adobe-reader-extensions-client.jar
adobe-signatures-client.jar

Forms服務

SOAP

WebLogic

adobe-livecycle-client.jar
adobe-usermanager-client.jar
wlclient.jar
activation.jar
axis.jar
commons-codec-1.3.jar
commons-collections-3.1.jar
commons-discovery.jar
commons-logging.jar
dom3-xml-apis-2.5.0.jar
jai_imageio.jar
jaxen-1.1-beta-9.jar
jaxrpc.jar
log4j.jar
mail.jar
saaj.jar
wsdl4j.jar
xalan.jar
xbean.jar
xercesImpl.jar
adobe-forms-client.jar

Forms服務

Acrobat Reader DC擴充功能服務

簽章服務

SOAP

WebLogic

adobe-livecycle-client.jar
adobe-usermanager-client.jar
wlclient.jar
activation.jar
axis.jar
commons-codec-1.3.jar
commons-collections-3.1.jar
commons-discovery.jar
commons-logging.jar
dom3-xml-apis-2.5.0.jar
jai_imageio.jar
jaxen-1.1-beta-9.jar
jaxrpc.jar
log4j.jar
mail.jar
saaj.jar
wsdl4j.jar
xalan.jar
xbean.jar
xercesImpl.jar
adobe-forms-client.jar
adobe-reader-extensions-client.jar
adobe-signatures-client.jar

升級JAR檔案

如果您從LiveCycle升級為AEM Forms，建議您在Java專案的類別路徑中包含AEM Forms JAR檔案。例如，如果您使用Rights Management服務等服務，如果您未在類別路徑中包含AEM Forms JAR檔案，則會遇到相容性問題。

假設您要升級至AEM Forms。若要使用叫用Rights Management服務的Java應用程式，請包含下列JAR檔案的AEM Forms版本：

adobe-rightsmanagement-client.jar
adobe-livecycle-client.jar
adobe-usermanager-client.jar

另請參閱

使用Java API叫用AEM Forms

設定連線屬性

使用Java API傳遞資料至AEM Forms服務

使用Java使用者端程式庫叫用服務

設定連線屬性

使用Java API時，您可以設定連線屬性來叫用AEM Forms。設定連線屬性時，請指定從遠端還是從本機叫用服務，同時指定連線模式和驗證值。如果啟用了服務安全性，則需要驗證值。但是，如果停用服務安全性，則不需要指定驗證值。

連線模式可以是SOAP或EJB模式。 EJB模式使用RMI/IIOP通訊協定，而EJB模式的效能比SOAP模式的效能好。 SOAP模式用於消除J2EE應用程式伺服器相依性，或當防火牆位於AEM Forms和使用者端應用程式之間時。 SOAP模式使用https通訊協定做為基礎傳輸，而且可以跨防火牆邊界通訊。如果J2EE應用程式伺服器相依性或防火牆都不是問題，建議您使用EJB模式。

若要成功叫用AEM Forms服務，請設定下列連線屬性：

DSC_DEFAULT_EJB_ENDPOINT： 如果您使用EJB連線模式，此值代表部署AEM Forms之J2EE應用程式伺服器的URL。若要從遠端叫用AEM Forms，請指定部署AEM Forms的J2EE應用程式伺服器名稱。如果您的使用者端應用程式位於相同的J2EE應用程式伺服器上，則可以指定localhost。視建置AEM Forms的J2EE應用程式伺服器而定，請指定下列其中一個值：
- JBoss： https://<ServerName>:8080 (default port)
- WebSphere： iiop://<ServerName>:2809 (default port)
- WebLogic： t3://<ServerName>:7001 (default port)
DSC_DEFAULT_SOAP_ENDPOINT：如果您使用SOAP連線模式，此值代表叫用要求傳送到的端點。若要從遠端叫用AEM Forms，請指定部署AEM Forms的J2EE應用程式伺服器名稱。如果您的使用者端應用程式位於相同的J2EE應用程式伺服器上，您可以指定localhost （例如，http://localhost:8080）。
- 如果J2EE應用程式是JBoss，則通訊埠值8080適用。如果J2EE應用程式伺服器是IBM® WebSphere®，請使用連線埠9080。同樣地，如果J2EE應用程式伺服器是WebLogic，請使用連線埠7001。 (這些值是預設的連線埠值。如果您變更連線埠值，請使用適用的連線埠號碼。)
DSC_TRANSPORT_PROTOCOL：如果您使用EJB連線模式，請為此值指定ServiceClientFactoryProperties.DSC_EJB_PROTOCOL。如果您使用SOAP連線模式，請指定ServiceClientFactoryProperties.DSC_SOAP_PROTOCOL。
DSC_SERVER_TYPE：指定部署AEM Forms的J2EE應用程式伺服器。有效值為JBoss、WebSphere、WebLogic。
- 如果您將此連線屬性設為WebSphere，則java.naming.factory.initial值會設為com.ibm.ws.naming.util.WsnInitCtxFactory。
- 如果您將此連線屬性設為WebLogic，則java.naming.factory.initial值會設為weblogic.jndi.WLInitialContextFactory。
- 同樣地，如果您將此連線屬性設為JBoss，則java.naming.factory.initial值會設為org.jnp.interfaces.NamingContextFactory。
- 如果您不想使用預設值，您可以將java.naming.factory.initial屬性設定為符合您要求的值。
NOTE
您可以使用ServiceClientFactoryProperties類別的靜態成員，而不使用字串來設定DSC_SERVER_TYPE連線屬性。可以使用下列值： ServiceClientFactoryProperties.DSC_WEBSPHERE_SERVER_TYPE、ServiceClientFactoryProperties.DSC_WEBLOGIC_SERVER_TYPE或ServiceClientFactoryProperties.DSC_JBOSS_SERVER_TYPE。
DSC_CREDENTIAL_USERNAME： 指定AEM表單使用者名稱。使用者若要成功叫用AEM Forms服務，他們需要服務使用者角色。使用者也可以擁有其他包含「服務啟動」許可權的角色。否則，當他們嘗試叫用服務時，會擲回例外狀況。如果停用服務安全性，則不需要指定此連線屬性。
DSC_CREDENTIAL_PASSWORD： 指定對應的密碼值。如果停用服務安全性，則不需要指定此連線屬性。
DSC_REQUEST_TIMEOUT： SOAP要求的預設要求逾時限製為1200000毫秒（20分鐘）。有時候，要求可能需要更長的時間才能完成作業。例如，擷取大量記錄的SOAP要求可能需要較長的逾時限制。您可以使用ServiceClientFactoryProperties.DSC_REQUEST_TIMEOUT來增加SOAP要求的要求呼叫逾時限制。

注意：只有SOAP型呼叫支援DSC_REQUEST_TIMEOUT屬性。

若要設定連線內容，請執行下列工作：

使用物件的建構函式建立java.util.Properties物件。
若要設定DSC_DEFAULT_EJB_ENDPOINT連線屬性，請叫用java.util.Properties物件的setProperty方法，並傳遞下列值：
- ServiceClientFactoryProperties.DSC_DEFAULT_EJB_ENDPOINT列舉值
- 字串值，指定代管AEM Forms之J2EE應用程式伺服器的URL
NOTE
如果您使用SOAP連線模式，請指定ServiceClientFactoryProperties.DSC_DEFAULT_SOAP_ENDPOINT列舉值，而非ServiceClientFactoryProperties.DSC_DEFAULT_EJB_ENDPOINT列舉值。
若要設定DSC_TRANSPORT_PROTOCOL連線屬性，請叫用java.util.Properties物件的setProperty方法，並傳遞下列值：
- ServiceClientFactoryProperties.DSC_TRANSPORT_PROTOCOL列舉值
- ServiceClientFactoryProperties.DSC_EJB_PROTOCOL列舉值
NOTE
如果您使用SOAP連線模式，請指定ServiceClientFactoryProperties.DSC_SOAP_PROTOCOL列舉值，而非ServiceClientFactoryProperties.DSC_EJB_PROTOCOL列舉值。
若要設定DSC_SERVER_TYPE連線屬性，請叫用java.util.Properties物件的setProperty方法，並傳遞下列值：
- ServiceClientFactoryProperties.DSC_SERVER_TYPE列舉值
- 字串值，指定代管AEM Forms的J2EE應用程式伺服器(例如，如果AEM Forms部署在JBoss上，請指定JBoss)。
  1. 若要設定DSC_CREDENTIAL_USERNAME連線屬性，請叫用java.util.Properties物件的setProperty方法，並傳遞下列值：
- ServiceClientFactoryProperties.DSC_CREDENTIAL_USERNAME列舉值
- 字串值，指定呼叫AEM Forms所需的使用者名稱
  1. 若要設定DSC_CREDENTIAL_PASSWORD連線屬性，請叫用java.util.Properties物件的setProperty方法，並傳遞下列值：
- ServiceClientFactoryProperties.DSC_CREDENTIAL_PASSWORD列舉值
- 字串值，指定對應的密碼值

正在設定JBoss的EJB連線模式

以下Java程式碼範例會設定連線屬性，以叫用部署在JBoss上的AEM Forms，並使用EJB連線模式。

 Properties ConnectionProps = new Properties();
 ConnectionProps.setProperty(ServiceClientFactoryProperties.DSC_DEFAULT_EJB_ENDPOINT, "https://<hostname>:8080");
 ConnectionProps.setProperty(ServiceClientFactoryProperties.DSC_TRANSPORT_PROTOCOL,ServiceClientFactoryProperties.DSC_EJB_PROTOCOL);
 ConnectionProps.setProperty(ServiceClientFactoryProperties.DSC_SERVER_TYPE, "JBoss");
 ConnectionProps.setProperty(ServiceClientFactoryProperties.DSC_CREDENTIAL_USERNAME, "administrator");
 ConnectionProps.setProperty(ServiceClientFactoryProperties.DSC_CREDENTIAL_PASSWORD, "password");
 ConnectionProps.setProperty(ServiceClientFactoryProperties.DSC_DOCUMENT_HTTP_ENDPOINT,"https://<hostname>:8080");

正在設定WebLogic的EJB連線模式

下列Java程式碼範例會設定連線屬性，以叫用建置在WebLogic上的AEM Forms，並使用EJB連線模式。

 Properties ConnectionProps = new Properties();
 ConnectionProps.setProperty(ServiceClientFactoryProperties.DSC_DEFAULT_EJB_ENDPOINT, "t3://localhost:7001");
 ConnectionProps.setProperty(ServiceClientFactoryProperties.DSC_TRANSPORT_PROTOCOL,ServiceClientFactoryProperties.DSC_EJB_PROTOCOL);
 ConnectionProps.setProperty(ServiceClientFactoryProperties.DSC_SERVER_TYPE, "WebLogic");
 ConnectionProps.setProperty(ServiceClientFactoryProperties.DSC_CREDENTIAL_USERNAME, "administrator");
 ConnectionProps.setProperty(ServiceClientFactoryProperties.DSC_CREDENTIAL_PASSWORD, "password");

正在設定WebSphere的EJB連線模式

下列Java程式碼範例會設定連線屬性，以叫用建置在WebSphere上的AEM Forms，並使用EJB連線模式。

 Properties ConnectionProps = new Properties();
 ConnectionProps.setProperty(ServiceClientFactoryProperties.DSC_DEFAULT_EJB_ENDPOINT, "iiop://localhost:2809");
 ConnectionProps.setProperty(ServiceClientFactoryProperties.DSC_TRANSPORT_PROTOCOL,ServiceClientFactoryProperties.DSC_EJB_PROTOCOL);
 ConnectionProps.setProperty(ServiceClientFactoryProperties.DSC_SERVER_TYPE, "WebSphere");
 ConnectionProps.setProperty(ServiceClientFactoryProperties.DSC_CREDENTIAL_USERNAME, "administrator");
 ConnectionProps.setProperty(ServiceClientFactoryProperties.DSC_CREDENTIAL_PASSWORD, "password");

正在設定SOAP連線模式

以下Java程式碼範例會在SOAP模式下設定連線屬性，以叫用部署在JBoss上的AEM Forms。

 Properties ConnectionProps = new Properties();
 ConnectionProps.setProperty(ServiceClientFactoryProperties.DSC_DEFAULT_SOAP_ENDPOINT, "http://localhost:8080");
 ConnectionProps.setProperty(ServiceClientFactoryProperties.DSC_TRANSPORT_PROTOCOL,ServiceClientFactoryProperties.DSC_SOAP_PROTOCOL);
 ConnectionProps.setProperty(ServiceClientFactoryProperties.DSC_SERVER_TYPE, "JBoss");
 ConnectionProps.setProperty(ServiceClientFactoryProperties.DSC_CREDENTIAL_USERNAME, "administrator");
 ConnectionProps.setProperty(ServiceClientFactoryProperties.DSC_CREDENTIAL_PASSWORD, "password");

NOTE

如果您選取SOAP連線模式，請確定在使用者端應用程式的類別路徑中包含其他JAR檔案。

在停用服務安全性時設定連線內容

以下Java程式碼範例會設定呼叫JBoss Application Server上部署的AEM Forms以及停用服務安全性時所需的連線屬性。

 Properties ConnectionProps = new Properties();
 ConnectionProps.setProperty(ServiceClientFactoryProperties.DSC_DEFAULT_EJB_ENDPOINT, "jnp://localhost:1099");
 ConnectionProps.setProperty(ServiceClientFactoryProperties.DSC_TRANSPORT_PROTOCOL,ServiceClientFactoryProperties.DSC_EJB_PROTOCOL);
 ConnectionProps.setProperty(ServiceClientFactoryProperties.DSC_SERVER_TYPE, "JBoss");

NOTE

與「使用AEM Forms程式設計」相關聯的所有Java快速入門都會顯示EJB和SOAP連線設定。

使用自訂要求逾時限制設定SOAP連線模式

 Properties ConnectionProps = new Properties();
 ConnectionProps.setProperty(ServiceClientFactoryProperties.DSC_DEFAULT_SOAP_ENDPOINT, "http://localhost:8080");
 ConnectionProps.setProperty(ServiceClientFactoryProperties.DSC_TRANSPORT_PROTOCOL,ServiceClientFactoryProperties.DSC_SOAP_PROTOCOL);
 ConnectionProps.setProperty(ServiceClientFactoryProperties.DSC_SERVER_TYPE, "JBoss");
 ConnectionProps.setProperty(ServiceClientFactoryProperties.DSC_CREDENTIAL_USERNAME, "administrator");
 ConnectionProps.setProperty(ServiceClientFactoryProperties.DSC_CREDENTIAL_PASSWORD, "password");
ConnectionProps.setProperty(ServiceClientFactoryProperties.DSC_REQUEST_TIMEOUT, "1800000"); // Request timeout limit 30 Minutes

使用內容物件來叫用AEM Forms

您可以使用com.adobe.idp.Context物件來叫用具有已驗證使用者的AEM Forms服務（com.adobe.idp.Context物件代表已驗證的使用者）。使用com.adobe.idp.Context物件時，您不需要設定DSC_CREDENTIAL_USERNAME或DSC_CREDENTIAL_PASSWORD屬性。您可以使用AuthenticationManagerServiceClient物件的authenticate方法在驗證使用者時取得com.adobe.idp.Context物件。

authenticate方法傳回包含驗證結果的AuthResult物件。您可以透過叫用它的建構函式來建立com.adobe.idp.Context物件。接著叫用com.adobe.idp.Context物件的initPrincipal方法並傳遞AuthResult物件，如下列程式碼所示：

 Context myCtx = new Context();
 myCtx.initPrincipal(authResult);

您可以叫用ServiceClientFactory物件的setContext方法並傳遞com.adobe.idp.Context物件，而不設定DSC_CREDENTIAL_USERNAME或DSC_CREDENTIAL_PASSWORD屬性。使用AEM表單使用者叫用服務時，請確定他們具有叫用AEM Forms服務所需的名為Services User的角色。

下列程式碼範例說明如何在用來建立EncryptionServiceClient物件的連線設定中使用com.adobe.idp.Context物件。

 //Authenticate a user and use the Context object within connection settings
 // Authenticate the user
 String username = "wblue";
 String password = "password";
 AuthResult authResult = authClient.authenticate(username, password.getBytes());

 //Set a Content object that represents the authenticated user
 //Use the Context object to invoke the Encryption service
 Context myCtx = new Context();
 myCtx.initPrincipal(authResult);

 //Set connection settings
 Properties connectionProps = new Properties();
 connectionProps.setProperty(ServiceClientFactoryProperties.DSC_DEFAULT_EJB_ENDPOINT, "jnp://<server>:1099");
 connectionProps.setProperty(ServiceClientFactoryProperties.DSC_TRANSPORT_PROTOCOL, ServiceClientFactoryProperties.DSC_EJB_PROTOCOL);
 connectionProps.setProperty(ServiceClientFactoryProperties.DSC_SERVER_TYPE, ServiceClientFactoryProperties.DSC_JBOSS_SERVER_TYPE);
 connectionProps.setProperty(ServiceClientFactoryProperties.DSC_DOCUMENT_HTTP_ENDPOINT,"jnp://<server>:1099");


 //Create a ServiceClientFactory object
 ServiceClientFactory myFactory = ServiceClientFactory.createInstance(connectionProps);
 myFactory.setContext(myCtx);

 //Create an EncryptionServiceClient object
 EncryptionServiceClient encryptClient  = new EncryptionServiceClient(myFactory);

NOTE

如需有關驗證使用者的完整詳細資訊，請參閱驗證使用者。

叫用案例

本節將討論下列叫用案例：

在其自己的Java虛擬機器器(JVM)中執行的使用者端應用程式會叫用獨立的AEM Forms執行個體。
在其自己的JVM中執行的使用者端應用程式會叫用叢集化AEM Forms執行個體。

叫用獨立AEM Forms執行個體的使用者端應用程式

下圖顯示在其自己JVM中執行並叫用獨立AEM Forms執行個體的使用者端應用程式。

在此案例中，使用者端應用程式在其自己的JVM中執行，並叫用AEM Forms服務。

NOTE

此案例是所有快速入門所依據的叫用案例。

叫用叢集AEM Forms執行個體的使用者端應用程式

下圖顯示在其自己的JVM中執行並叫用叢集中的AEM Forms執行個體的使用者端應用程式。

此案例類似於叫用獨立AEM Forms例項的使用者端應用程式。不過，提供者URL不同。如果從屬端應用程式想要連線到特定的J2EE應用程式伺服器，應用程式必須將URL變更為參照特定的J2EE應用程式伺服器。

不建議參考特定的J2EE應用程式伺服器，因為如果應用程式伺服器停止，使用者端應用程式和AEM Forms之間的連線就會終止。建議提供者URL參考儲存格層級JNDI管理員，而非特定的J2EE應用程式伺服器。

使用SOAP連線模式的使用者端應用程式可以使用叢集的HTTP負載平衡器連線埠。使用EJB連線模式的從屬端應用程式可以連線到特定J2EE應用程式伺服器的EJB連線埠。此動作會處理叢集節點之間的負載平衡。

WebSphere

下列範例顯示用來連線至WebSphere上所部署AEM Forms的jndi.properties檔案內容。

 java.naming.factory.initial=com.ibm.websphere.naming.
 WsnInitialContextFactory
 java.naming.provider.url=corbaloc::appserver1:9810,:appserver2:9810

WebLogic

下面的示例演示用於連接到部署在 WebLogic 上的AEM Forms的 jndi.properties 文件的內容。

 java.naming.factory.initial=weblogic.jndi.WLInitialContextFactory
 java.naming.provider.url=t3://appserver1:8001, appserver2:8001

JBoss

以下示例顯示了用於連接到部署在 JBoss 上的AEM Forms的 jndi.properties 文件的內容。

 java.naming.factory.initial= org.jnp.interfaces.NamingContextFactory
 java.naming.provider.url= jnp://appserver1:1099, appserver2:1099,
 appserver3:1099

NOTE

請洽詢您的管理員，以確定J2EE應用程式伺服器名稱和連線埠號碼。

另請參閱

包括 AEM Forms Java 資料庫檔案

使用 Java API 將數據傳遞至 AEM Forms 服務

使用 Java 客戶機資料庫叫用服務

使用 Java API 將數據傳遞至 AEM Forms 服務

AEM Forms服務作業通常會消耗或產生PDF檔案。當您叫用服務時，有時必須將PDF檔案（或其他檔案型別，例如XML資料）傳遞給服務。同樣地，有時候，處理從服務傳回的PDF檔案也是必要的。可讓您在AEM Forms服務之間傳遞資料的Java類別是com.adobe.idp.Document。

AEM Forms服務不接受PDF檔案做為其他資料型別，例如java.io.InputStream物件或位元組陣列。 com.adobe.idp.Document物件也可用來將其他型別的資料（例如XML資料）傳遞至服務。

com.adobe.idp.Document物件是Java可序列化型別，因此可透過RMI呼叫傳遞。接收端可以並置（相同主機、相同類別載入器）、本機（相同主機、不同類別載入器）或遠端（不同主機）。檔案內容的傳遞已針對每個案例最佳化。例如，如果傳送者與接收者位在相同主機上，則內容會透過本機檔案系統傳遞。（在某些情況下，檔案可以在記憶體中傳遞。）

根據com.adobe.idp.Document物件大小，資料會在com.adobe.idp.Document物件中攜帶或儲存在伺服器的檔案系統中。 com.adobe.idp.Document物件所佔用的任何暫存資源會在com.adobe.idp.Document處置時自動移除。（請參閱處置檔案物件。）

有時您必須先知道com.adobe.idp.Document物件的內容型別，才能將其傳遞給服務。例如，如果作業需要特定內容型別（例如application/pdf），建議您決定內容型別。（請參閱決定檔案的內容型別。）

com.adobe.idp.Document物件會嘗試使用提供的資料來判斷內容型別。如果無法從提供的資料中擷取內容型別（例如，當資料以位元組陣列提供時），請設定內容型別。若要設定內容型別，請叫用com.adobe.idp.Document物件的setContentType方法。（請參閱決定檔案的內容型別）

如果附屬檔案位於相同的檔案系統上，建立com.adobe.idp.Document物件會更快。如果附屬檔案位於遠端檔案系統上，則必須進行複製操作，這會影響效能。

應用程式可包含com.adobe.idp.Document和org.w3c.dom.Document資料型別。不過，請確定您已完全符合org.w3c.dom.Document資料型別的資格。如需有關將org.w3c.dom.Document物件轉換為com.adobe.idp.Document物件的資訊，請參閱快速入門（EJB模式）：使用Java API預先填入Forms的可流程配置。

NOTE

若要防止使用com.adobe.idp.Document物件時WebLogic中的記憶體洩漏，請以2048個位元組或更少的區塊讀取檔案資訊。例如，下列程式碼會以2048位元組的區塊讀取檔案資訊：

        // Set up the chunk size to prevent a potential memory leak
        int buffSize = 2048;

        // Determine the total number of bytes to read
        int docLength = (int) inDoc.length();
        byte [] byteDoc = new byte[docLength];

        // Set up the reading position
        int pos = 0;

        // Loop through the document information, 2048 bytes at a time
        while (docLength > 0) {
      // Read the next chunk of information
            int toRead = Math.min(buffSize, docLength);
            int bytesRead = inDoc.read(pos, byteDoc, pos, toRead);

            // Handle the exception in case data retrieval failed
            if (bytesRead == -1) {

                inDoc.doneReading();
                inDoc.dispose();
                throw new RuntimeException("Data retrieval failed!");

            }

             // Update the reading position and number of bytes remaining
             pos += bytesRead;
             docLength -= bytesRead;

        }

        // The document information has been successfully read
        inDoc.doneReading();
        inDoc.dispose();

另請參閱

使用Java API叫用AEM Forms

設定連線屬性

建立檔案

啟動需要PDF檔案（或其他檔案型別）作為輸入值的服務作業之前，請先建立com.adobe.idp.Document物件。 com.adobe.idp.Document類別提供的建構函式可讓您從下列內容型別建立檔案：

位元組陣列
現有的com.adobe.idp.Document物件
java.io.File物件
java.io.InputStream物件
java.net.URL物件

根據位元組陣列建立檔案

下列程式碼範例會建立以位元組陣列為基礎的com.adobe.idp.Document物件。

建立以位元組陣列為基礎的Document物件

 Document myPDFDocument = new Document(myByteArray);

根據其他檔案建立檔案

下列程式碼範例會建立以其他com.adobe.idp.Document物件為基礎的com.adobe.idp.Document物件。

建立以其他檔案為基礎的檔案物件

 //Create a Document object based on a byte array
 InputStream is = new FileInputStream("C:\\Map.pdf");
 int len = is.available();
 byte [] myByteArray = new byte[len];
 int i = 0;
 while (i < len) {
       i += is.read(myByteArray, i, len);
 }
 Document myPDFDocument = new Document(myByteArray);

 //Create another Document object
 Document anotherDocument = new Document(myPDFDocument);

根據檔案建立檔案

下列程式碼範例會建立以名為 map.pdf 的PDF檔案為基礎的com.adobe.idp.Document物件。此檔案位於C硬碟的根目錄。此建構函式會嘗試使用副檔名來設定com.adobe.idp.Document物件的MIME內容型別。

接受java.io.File物件的com.adobe.idp.Document建構函式也接受布林引數。透過將此引數設定為true，com.adobe.idp.Document物件會刪除檔案。此動作表示您將檔案傳遞至com.adobe.idp.Document建構函式後，不必移除檔案。

將此引數設定為false表示您保留此檔案的所有權。將此引數設定為true會更有效率。原因在於com.adobe.idp.Document物件可以直接將檔案移至本機Managed區域，而非複製檔案（速度較慢）。

建立以PDF檔案為基礎的Document物件

 //Create a Document object based on the map.pdf source file
 File mySourceMap = new File("C:\\map.pdf");
 Document myPDFDocument = new Document(mySourceMap,true);

根據InputStream物件建立檔案

下列Java程式碼範例會建立以java.io.InputStream物件為基礎的com.adobe.idp.Document物件。

根據InputStream物件建立檔案

 //Create a Document object based on an InputStream object
 InputStream is = new FileInputStream("C:\\Map.pdf");
 Document myPDFDocument = new Document(is);

根據可從URL存取的內容建立檔案

以下Java程式碼範例會根據名為 map.pdf 的PDF檔案來建立com.adobe.idp.Document物件。此檔案位於名為WebApp的Web應用程式中，該應用程式正在localhost上執行。此建構函式會嘗試使用URL通訊協定傳回的內容型別來設定com.adobe.idp.Document物件的MIME內容型別。

提供給com.adobe.idp.Document物件的URL一律會在建立原始com.adobe.idp.Document物件的一側讀取，如以下範例所示：

     Document doc = new Document(new java.net.URL("file:c:/temp/input.pdf"));

c：/temp/input.pdf 文件必須位於用戶端電腦上（而不是伺服器計算機上）。用戶端電腦是讀取URL和 com.adobe.idp.Document 創建物件的位置。

根據可從URL存取內容建立文件

 //Create a Document object based on a java.net.URL object
 URL myURL = new URL("http", "localhost", 8080,"/WebApp/map.pdf");

 //Create another Document object
 Document myPDFDocument = new Document(myURL);

另請參閱

使用Java API叫用AEM Forms

設定連線屬性

處理傳回的檔案

返回 PDF 檔（或其他資料類型，如 XML 資料）作為輸出值的服務操作傳回物件 com.adobe.idp.Document 。收到 com.adobe.idp.Document 物件后，可以將其轉換為以下格式：

物件java.io.File
物件java.io.InputStream
位元組陣列

下列程式碼行會將com.adobe.idp.Document物件轉換為java.io.InputStream物件。假設myPDFDocument代表com.adobe.idp.Document物件：

     java.io.InputStream resultStream = myDocument.getInputStream();

同樣地，您可以執行下列工作，將com.adobe.idp.Document的內容複製到本機檔案：

建立java.io.File物件。
叫用com.adobe.idp.Document物件的copyToFile方法並傳遞java.io.File物件。

下列程式碼範例將com.adobe.idp.Document物件的內容複製到名為 AnotherMap.pdf 的檔案。

正在複製檔案物件的內容至檔案

 File outFile = new File("C:\\AnotherMap.pdf");
 myDocument.copyToFile (outFile);

另請參閱

使用Java API叫用AEM Forms

設定連線屬性

決定檔案的內容型別

呼叫com.adobe.idp.Document物件的getContentType方法，判斷com.adobe.idp.Document物件的MIME型別。此方法會傳回字串值，指定com.adobe.idp.Document物件的內容型別。下表說明AEM Forms傳回的不同內容型別。

MIME型別

說明

application/pdf

PDF檔案

application/vnd.adobe.xdp+xml

XML資料封裝(XDP)用於轉存的XML Forms架構(XFA)表單

text/xml

書籤、附件或其他XML檔案

application/vnd.fdf

Forms資料格式(FDF)，用於轉存的Acrobat表單

application/vnd.adobe.xfdf

XML Forms資料格式(XFDF)，用於轉存的Acrobat表單

application/rdf+xml

豐富資料格式和XML

application/octet-stream

通用資料格式

NULL

未指定的MIME型別

下列程式碼範例決定com.adobe.idp.Document物件的內容型別。

正在決定Document物件的內容型別

 //Determine the content type of the Document object
 String ct = myDocument.getContentType();
 System.out.println("The content type of the Document object is " +ct);

另請參閱

使用Java API叫用AEM Forms

設定連線屬性

處置檔案物件

當您不再需要Document物件時，建議您叫用其dispose方法來處置它。每個Document物件會佔用一個檔案描述元，以及應用程式主機平台上最多75 MB的RAM空間。如果未處置Document物件，則Java Garage收集程式會將其處置。不過，使用dispose方法儘快處置它，您就可以釋放Document物件所佔用的記憶體。

另請參閱

使用Java API叫用AEM Forms

包含AEM Forms Java程式庫檔案

使用Java使用者端程式庫叫用服務

使用Java使用者端程式庫叫用服務

AEM Forms服務作業可使用服務的強型別API （稱為Java使用者端程式庫）來叫用。 Java使用者端程式庫 是一組提供存取服務容器中部署之服務的具體類別。您將Java物件例項化，該物件代表要叫用的服務，而不是使用叫用API建立InvocationRequest物件。「叫用API」可用來叫用在Workbench中建立的程式，例如長期程式。（請參閱叫用以人為中心的長期流程。）

若要執行服務作業，請叫用屬於Java物件的方法。 Java使用者端程式庫所包含的方法，通常會將服務操作對應到一。使用Java使用者端程式庫時，請設定必要的連線屬性。（請參閱設定連線屬性。）

在您設定連線屬性之後，請建立ServiceClientFactory物件，用來具現化Java物件，讓您叫用服務。每個具有Java使用者端程式庫的服務都有對應的使用者端物件。例如，若要叫用存放庫服務，請使用它的建構函式並傳遞ServiceClientFactory物件來建立ResourceRepositoryClient物件。 ServiceClientFactory物件負責維護呼叫AEM Forms服務所需的連線設定。

雖然取得ServiceClientFactory通常很快，但在第一次使用工廠時會產生一些額外負荷。此物件已針對重複使用而最佳化，因此，當您建立多個Java使用者端物件時，請儘可能使用相同的ServiceClientFactory物件。也就是說，請勿為您建立的每個使用者端程式庫物件建立個別的ServiceClientFactory物件。

有一個使用者管理員設定可控制影響ServiceClientFactory物件的com.adobe.idp.Context物件內SAML宣告的存留期。此設定會控制整個AEM Forms的所有驗證內容存留期，包括使用Java API執行的所有叫用。根據預設，可以使用ServiceCleintFactory物件的時段為兩個小時。

NOTE

若要說明如何使用Java API來叫用服務，會叫用儲存庫服務的writeResource作業。此操作會將新資源放入存放庫中。

您可以使用 Java 客戶機資料庫並執行以下步驟來呼叫儲存庫服務：

將用戶端 JAR 檔案（例如 adobe-存放庫-client.jar）包含在 Java 專案的類別路徑中。有關這些檔的位置的資訊，請參閱包括AEM Forms Java 資料庫檔。
設置調用服務所需的連接屬性。
呼叫ServiceClientFactory物件的靜態createInstance方法，並傳遞包含連線屬性的java.util.Properties物件，以建立ServiceClientFactory物件。
使用它的建構函式並傳遞ServiceClientFactory物件來建立ResourceRepositoryClient物件。使用該 ResourceRepositoryClient 物件來調用存儲庫服務操作。
RepositoryInfomodelFactoryBean使用物件的建構函數建立物件並傳遞 null.此物件允許您創建一個 Resource 表示添加到存放庫內容的物件。
Resource通過調用RepositoryInfomodelFactoryBean物件的方法newImage並傳遞以下值來建立物件：
- 唯一 ID 值，方法是指定 new Id().
- 藉由指定new Lid()來指定唯一的UUID值。
- 資源的名稱。您可以指定XDP檔案的檔案名稱。
將傳回值轉換為Resource。
呼叫RepositoryInfomodelFactoryBean物件的newImage方法，並將傳回值轉型為ResourceContent，以建立ResourceContent物件。此物件代表新增至存放庫的內容。
傳遞儲存XDP檔案以新增至儲存庫的java.io.FileInputStream物件，以建立com.adobe.idp.Document物件。（請參閱根據InputStream物件建立檔案。）
呼叫ResourceContent物件的setDataDocument方法，將com.adobe.idp.Document物件的內容新增至ResourceContent物件。傳遞com.adobe.idp.Document物件。
呼叫ResourceContent物件的setMimeType方法並傳遞application/vnd.adobe.xdp+xml，以將XDP檔案的MIME型別設定為加入儲存庫。
呼叫Resource物件的setContent方法並傳遞ResourceContent物件，將ResourceContent物件的內容新增至Resource物件。
叫用Resource物件的setDescription方法並傳遞代表資源說明的字串值，以新增資源的說明。
叫用ResourceRepositoryClient物件的writeResource方法並傳遞下列值，以將表單設計加入儲存庫：
- 字串值，指定包含新資源的資源集合的路徑
- 已建立的Resource物件

另請參閱

快速入門（EJB模式）：使用Java API寫入資源

使用Java API叫用AEM Forms

包含AEM Forms Java程式庫檔案

使用叫用API叫用短期程式

您可以使用Java叫用API來叫用短期流程。當您使用叫用API叫用短期處理程式時，您會使用java.util.HashMap物件傳遞必要的引數值。對於要傳遞給服務的每個引數，請叫用java.util.HashMap物件的put方法，並指定服務執行指定作業所需的名稱 — 值組。指定屬於短期處理序之引數的確切名稱。

NOTE

如需有關叫用長效處理序的資訊，請參閱叫用以人為中心的長效處理序。

此處的討論內容是關於使用引動API來叫用下列名為MyApplication/EncryptDocument的AEM Forms短期處理序。

NOTE

此程式並非以現有AEM Forms程式為基礎。若要跟隨程式碼範例，請使用Workbench建立名為MyApplication/EncryptDocument的程式。（請參閱使用Workbench。）

叫用此程式時，會執行下列動作：

取得傳遞至程式的不安全PDF檔案。此動作是以SetValue作業為基礎。此處理序的輸入引數是名為inDoc的document處理序變數。
使用密碼加密PDF檔案。此動作是以PasswordEncryptPDF作業為基礎。密碼加密的PDF檔案傳回名為outDoc的程式變數。

使用Java叫用API叫用MyApplication/EncryptDocument短期程式

使用Java叫用API叫用MyApplication/EncryptDocument短期處理序：

在您的Java專案的類別路徑中包含使用者端JAR檔案，例如adobe-livecycle-client.jar。 (請參閱包含AEM Forms Java程式庫檔案。)
建立包含連線屬性的ServiceClientFactory物件。（請參閱設定連線屬性。）
使用它的建構函式並傳遞ServiceClientFactory物件來建立ServiceClient物件。 ServiceClient物件可讓您叫用服務作業。它會處理如尋找、分派及路由呼叫要求等工作。
使用物件的建構函式建立java.util.HashMap物件。
叫用每個輸入引數的java.util.HashMap物件的put方法，以傳遞至長效處理序。由於MyApplication/EncryptDocument短期處理程式需要一個型別Document的輸入引數，因此您只需要叫用put方法一次，如下列範例所示。
//Create a Map object to store the parameter value for inDoc Map params = new HashMap(); InputStream inFile = new FileInputStream("C:\\Adobe\Loan.pdf"); Document inDoc = new Document(inFile); params.put("inDoc", inDoc);
呼叫ServiceClientFactory物件的createInvocationRequest方法，並傳遞下列值以建立InvocationRequest物件：
- 字串值，指定要叫用的長效處理序名稱。若要叫用MyApplication/EncryptDocument處理序，請指定MyApplication/EncryptDocument。
- 代表處理作業名稱的字串值。一般而言，短期處理程式操作的名稱是invoke。
- 包含服務作業所需之引數值的java.util.HashMap物件。
- 指定true的布林值，會建立同步要求（此值適用於叫用短期處理程式）。
透過叫用ServiceClient物件的invoke方法並傳遞InvocationRequest物件來傳送呼叫要求給服務。 invoke方法傳回InvocationReponse物件。

NOTE
可透過傳遞值false作為createInvocationRequest方法的第四個引數來叫用長期處理序。傳遞值false會建立非同步要求。
叫用InvocationReponse物件的getOutputParameter方法，並傳遞指定輸出引數名稱的字串值，以擷取處理序的傳回值。在此情況下，請指定outDoc （outDoc是MyApplication/EncryptDocument處理序的輸出引數名稱）。將傳回值轉換為Document，如下列範例所示。
InvocationResponse response = myServiceClient.invoke(request); Document encryptDoc = (Document) response.getOutputParameter("outDoc");
建立java.io.File物件，並確定副檔名為.pdf。
叫用com.adobe.idp.Document物件的copyToFile方法，將com.adobe.idp.Document物件的內容複製到檔案。確定您使用的是getOutputParameter方法傳回的com.adobe.idp.Document物件。

另請參閱

快速入門：使用叫用API叫用短期流程

叫用以人為中心的長期流程

包含AEM Forms Java程式庫檔案

recommendation-more-help

19ffd973-7af2-44d0-84b5-d547b0dffee2