Thursday, April 09, 2009

This video show how to remotely invoke services using the APIs and SOAP endpoints. This contains step by step instructions for setting up the project, writing the code, and compiling and running the application.

UPDATE: If you cannot see the video, I have now posted it to Google video here:

Scott MacDonald and I created a tutorial to help LiveCycle ES developers better understand the process around using the Quick Start guides available from the LiveCycle area of the Adobe Developer Connection. In this tutorial, you will learn how to download and configure the code samples, configure the right JAR files, set user permissions, and invoke a LiveCycle ES SOAP endpoint to convert a PostScript file into a PDF file.

Before you start:

You will need to ensure you have the following on your local drive. I used a MacBook Pro laptop to conduct this lab.

Java JDK 1.5 – ensure your environment variables are set as per the instructions from the LiveCycle ES documentation

Eclipse 3.4 (Ganymede)

The LiveCycle ES Client SDK JAR files. You will need the following JAR files to make this lab work:

/** This Java Quick Start uses the EJB mode and contains the following JAR files* in the class path:* 1. adobe-encryption-client.jar* 2. adobe-livecycle-client.jar* 3. adobe-usermanager-client.jar* 4. adobe-utilities.jar* 5. jbossall-client.jar (use a different JAR file if LiveCycle ES is not* deployed on JBoss)** These JAR files are located in the following path:* {install directory}/Adobe/LiveCycle9.0/LiveCycle_ES_SDK/client-libs/common** The adobe-utilities.jar file is located in the following path:* {install directory}/Adobe/LiveCycle9.0/LiveCycle_ES_SDK/client-libs/jboss** The jbossall-client.jar file is located in the following path:* {install directory}/Adobe/LiveCycle9.0/jboss/client*/

You will also need the third-party JAR files to use the SOAP stack rather than EJB endpoints. If you want to invoke a remote LiveCycle ES instance and there is a firewall between the client application and LiveCycle ES, then it is recommended that you use the SOAP mode. When using the SOAP mode, you have to include additional JAR files located in the following path:

For complete details about the location of the LiveCycle ES JAR files, see "Including LiveCycle ES library files" in Programming with LiveCycle ES.

1. Open up Eclipse and set up a new Java project by choosing File > New > Project.

2. Select Java Project.

3. Type a name for the project and click Finish.

4. When the new project opens in your workspace navigator, right-click (Windows) or Control-click (Mac) on the src folder under the project.

5. Choose New > Package.

6. Type a name for your package (I used “org.duanesworldtv.samples”) and click Finish. This step is important because it keeps your class files distinct from other class files with the same names under your workspace by namespace qualifying them.

7. Right-click on the package name you just created (under your project) and choose New > Class to create a new class file.

8. In the New Java Class dialog box, type the name for your class (I used “CreatePDF”) and click Finish.

9. You should see some skeleton code under your new project. Highlight all code below the package name and delete it.

11. When you paste this code into your project, you will notice several red Xs beside various lines. This is because you have not yet imported any of the LiveCycle ES JAR files.

There are a couple of gotchas you need to know about with respect to these JARs.

First, the JARs must be from the same release of LiveCycle as the instance you are going to connect to. JARs from 8.0, for example, might not always work with an 8.2.1 instance.

Second, the JARs are in various locations and not always easy to grab. (See above for the exact locations.)

We put our jars into a parallel directory that we created under our Eclipse workspace called “JavaOne2009_libs”. This allows us to easily use these JAR files for multiple projects.

12. To add the JARs to your project, highlight the project name in the navigator tab, then right-click and open the project Properties dialog box.

13. Select Java Build Path and then the Libraries tab. Click Add External Jars. Select all the JARs under the “thirdparty” folder (for SOAP only – these are not required for EJB endpoints invocation). You will also need to import the Adobe LiveCycle Client JARs. (Note: In the image below we have highlighted some extra jars because we plan to add more class files to this project later.)

14. Once your JAR files are added, your build path should look similar to this:

15. Click OK, check any warnings in Eclipse, and correct as needed.

16. Now locate the lines of code that set the connection properties. They are at around line 14 and look like this:

17. You will have to change three values. The first is the server IP address and port. If the server is on the same machine, http://localhost:8080 should suffice. Change it as required to match your server's location.

18. Next, you will be required to supply a username and password of a user with the right privileges. We used the username "kvarsen" because it is installed by default when you install the LiveCycle ES samples. The matching password for kvarsen is “password”, all lowercase.

To run the code in this tutorial, however, you will need to update the roles assigned to kvarsen. To do this, you must have administrator access to the LiveCycle Server you wish to connect to. Log in to the adminui at http://{your_server_ip}:{http_port}/adminui. For example, ours was http://duanesworldtv.org:8080/adminui. Once inside, navigate to Home > Settings > User Management > Users and Groups.

19. Type the user's name in the Find text box (for Kel Varsen, type “varsen”) and click Find. The user's name will come up in the list with a hyperlink. Click on the name to show what permissions the user has.

20. Click the Role Assignments tab.

21. This will bring up a screen that shows all the roles and permissions that this particular user has. For this tutorial, you want to ensure that Kel Varsen is privileged with the PDFG (PDF Generation) service. (In the screenshot below the user is already assigned the PDFG User role; your setup will likely not show this yet.)

22. To find the appropriate roles, click Find Roles, which will bring up a list.

23. Locate and select the PDFG User role, and then click OK. You can then log out of the adminui console.

24. You are almost ready to run the code. Back in Eclipse, you will notice two lines of code that contain path references. One is a reference to a PostScript document. You need to change this to correspond to an absolute path to a PostScript document on your hard drive. The path we used is:

// Get a PS file document to convert to a PDF document and populate a com.adobe.idp.Document objectString inputFileName = "/Users/duane/Desktop/eclipse/workspace/JavaOne2009-docs/test.ps";

25. Replace this path with a path to a valid Postscript file.

26. You also need to specify the path used to save the file when it comes back from LiveCycle ES. This is around line 72 and looks something like the code below. Change the path to a location on your system for which you have access.

27. Now run the application. You should see the console output working with no errors. Go to the location you referenced in the previous step and you should find a file there titled “DuanesWorldTest.pdf” or whatever you named your file.

Congratulations – you have just invoked your first remote SOAP endpoint using LiveCycle ES!

Tuesday, April 07, 2009

During the last year there has been a worsening financial crisis. While some may look at this as a bad thing, I look at it as opportunity. Have you ever thought about upgrading your skills? Wanted to work in high tech? If you recently lost your job, now might be the time - and Adobe (and the evangelism team) is here to help!

Inference: there is more demand than there is supply for skilled IT workers.

Rationale: Think about why. As the economy got worse, big firms failed and got acquired by others. What is the first thing they want done? Integration of computer systems and re-branding, both of which require programmers and architects. The demand is out there.

Solution: We are giving away FREE Flex Builder licenses to anyone who has recently been laid off. You can simply go to this location and apply:

Possibly a third at Hamburg. If you are interested in Hamburg training in the time frame of June 15-25, please drop me a comment here. Ja - ich kann auch Deutsche sphreche und ich liebe gut Deutches Bier!

I will also entertain coming to other cities around the world to help train those who are interested in changing their lives and joining us. We are all part of a global community and it is only an illusion that we are separate. What harms you harms me. What helps you helps me. Pay it forward and good karma shall be yours.

On top of that, Adobe has made one full week of video training available to take online. See here for details:

Pin it!

SHARE!

If you are helped by this blog in any way, or just find the contents interesting, please give it a share to help keep me publishing. Shares help drive my advertising revenue which makes me more likely to write articles to help people in the future. Thank you in advance!