Thursday, April 09, 2009

New LiveCycle Video Tutorial

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:

http://video.google.ca/videoplay?docid=2601122249633361252


Watch Adobe LiveCycle ES Java Service Invocation in Tech & Gaming | View More Free Videos Online at Veoh.com

Invoking the LiveCycle ES 8.2.1 Distiller API from Java

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:


/*
{install directory}/Adobe/LiveCycle9.0/LiveCycle_ES_SDK/client-
* libs/thirdparty
*/
 


For information about the SOAP and EJB mode, see "Setting connection properties" in Programming with LiveCycle ES.

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.

10. Replace the deleted skeleton code with this source code:

package org.duanesworldtv.samples;

/*
* This Java Quick Start uses the following JAR files
* 1. adobe-distiller-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:
* /Adobe/LiveCycle8/LiveCycle_ES_SDK/client-libs
*
* For complete details about the location of these JAR files,
* see "Including LiveCycle ES library files" in Programming
* with LiveCycle ES
*/
import java.io.File;
import java.io.FileInputStream;
import java.util.Properties;
import com.adobe.livecycle.generatepdf.client.CreatePDFResult;
import com.adobe.idp.Document;
import com.adobe.idp.dsc.clientsdk.ServiceClientFactory;
import com.adobe.idp.dsc.clientsdk.ServiceClientFactoryProperties;
import com.adobe.livecycle.distiller.client.DistillerServiceClient;

public class CreatePDF {

public static void main(String[] args)
{
try
{
//Set connection properties required to invoke LiveCycle ES
Properties ConnectionProps = new Properties();
ConnectionProps.setProperty(ServiceClientFactoryProperties.DSC_DEFAULT_SOAP_ENDPOINT, "http://{your_server_IP}:{HTTP_PORT}");
ConnectionProps.setProperty(ServiceClientFactoryProperties.DSC_TRANSPORT_PROTOCOL,ServiceClientFactoryProperties.DSC_SOAP_PROTOCOL);
ConnectionProps.setProperty(ServiceClientFactoryProperties.DSC_SERVER_TYPE, "JBoss");
ConnectionProps.setProperty(ServiceClientFactoryProperties.DSC_CREDENTIAL_USERNAME, "{username_of_privileged_user}");
ConnectionProps.setProperty(ServiceClientFactoryProperties.DSC_CREDENTIAL_PASSWORD, "{password}");

// Create a ServiceClientFactory instance
ServiceClientFactory factory = ServiceClientFactory.createInstance(ConnectionProps);

DistillerServiceClient disClient = new DistillerServiceClient(factory );

// Get a PS file document to convert to a PDF document and populate a com.adobe.idp.Document object
String inputFileName = "/Users/duane/Desktop/eclipse/workspace/JavaOne2009-docs/test.ps";
FileInputStream fileInputStream = new FileInputStream(inputFileName);
Document inDoc = new Document(fileInputStream);

//Set run-time options
String adobePDFSettings = "Standard";
String securitySettings = "No Security";

//Convert a PS file into a PDF file
CreatePDFResult result = new CreatePDFResult();
result = disClient.createPDF(
inDoc,
inputFileName,
adobePDFSettings,
securitySettings,
null,
null
);

//Get the newly created document
Document createdDocument = result.getCreatedDocument();

//Save the PDF file
createdDocument.copyToFile(new File("/Users/duane/Desktop/eclipse/workspace/JavaOne2009-docs/DuanesWorldTest.pdf"));
}
catch (Exception e) {
e.printStackTrace();
}
}
}

 


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:


//Set connection properties required to invoke LiveCycle ES
Properties ConnectionProps = new Properties();
ConnectionProps.setProperty(ServiceClientFactoryProperties.DSC_DEFAULT_SOAP_ENDPOINT, "http://{your_server_ip}:{http_port}");
ConnectionProps.setProperty(ServiceClientFactoryProperties.DSC_TRANSPORT_PROTOCOL,ServiceClientFactoryProperties.DSC_SOAP_PROTOCOL);
ConnectionProps.setProperty(ServiceClientFactoryProperties.DSC_SERVER_TYPE, "JBoss");
ConnectionProps.setProperty(ServiceClientFactoryProperties.DSC_CREDENTIAL_USERNAME, "{username_of_privileged_user}");
ConnectionProps.setProperty(ServiceClientFactoryProperties.DSC_CREDENTIAL_PASSWORD, "{password}");
 



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 object
String 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.

//Save the PDF file
createdDocument.copyToFile(new File("/Users/duane/Desktop/eclipse/workspace/JavaOne2009-docs/DuanesWorldTest.pdf"));
 


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

Adobe Stimulus Plan - free product, learn Flex in one Week!

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!

Fact: Flex and AIR developers are in short supply! Don't believe me, look at the search result below. Over 1.7 million results for "Flex Developer Wanted".

http://www.google.com/search?source=ig&hl=en&rlz=&=&q=flex+developers+wanted&btnG=Google+Search&aq=f&oq=


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:

https://freeriatools.adobe.com/

Of course, free tools don't just build stuff themselves so we need to help out even more and train you. I have taken it upon myself to do this and I have made a full day of training available here.

http://www.web2open.org/courses.html

On top of that, I have started some full day, hands-on intensive courses for those who want to learn how to use Flex Builder. There are two events scheduled.

Vancouver - May 28 - Full day 100% free Flex, AIR camp (details)

Berlin - June 14 - Full day 100% free Flex, AIR camp (details TBA)

and

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:

http://technoracle.blogspot.com/2009/03/learn-flex-in-one-week.html

Oh yeah - did I mention this is all free!

WOOT!

Monday, April 06, 2009

Registration open for free Flex/AIR training in Vancouver

Last month I blogged about a free developers day of training for Adobe Flex and AIR. The date has been set at May 28 and the registration is open:

http://flash.meetup.com/110/calendar/10129317/


This course will be largely hands-on and everyone there will build several applications and complete labs to get trained in RIA web development.

There are limited slots available and in the first hour almost 1/7 of the seats has gone. Register now!

Become an Adobe affiliate

Fan of Adobe? Want to make some extra cash? You may not be aware of this but there is an Adobe affiliate program in place to allow anyone to make money by referring customers to Adobe technologies.

Anyone (except Adobe employees!) can signup and direct folks to the online store -- any purchases made after referral receive a 6% commission. That's over $40 for a single copy of Flex Builder Pro.

Here are details on the program:

http://www.adobe.com/buy/affiliates/