Macromedia Version Cue - CS3 Getting Started

GETTING STARTED WITH ADOBE VERSION CUE CS3 DEVELOPMENT
© 2007 Adobe Systems Incorporated. All rights reserved.
Getting Started with Adobe Version Cue CS3 Development
Technical note #10300
Adobe, the Adobe logo, Bridge, Creative Suite, Version Cue, and Version Cue Server are either registered trademarks or trademarks of Adobe Systems Incorporated in the United States and/or other countries. Mac OS is a trademark of Apple Computer, Inc., registered in the United States and other countries. Windows is either a registered trademark or a trademark of Microsoft Corporation in the United States and/or other countries. Java is a trademark or registered trademark of Sun Microsystems, Inc. in the United States and other countries. All other trademarks are the property of their respective owners.
The information in this document is furnished for informational use only, is subject to change without notice, and should not be construed as a commitment by Adobe Systems Incorporated. Adobe Systems Incorporated assumes no responsibility or liability for any errors or inaccuracies that may appear in this document. The software described in this document is furnished under license and may only be used or copied in accordance with the terms of such license.
Contents
Terminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Development Platforms. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Setting up your Development Platform. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Installation and Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Stopping Version Cue CSx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Stopping the MySQL Database Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Preparing to Start Version Cue Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Running Version Cue Server for the First Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Starting Version Cue Server from the IDE of Version Cue SDK . . . . . . . . . . . . . . . . . . . . . 15
Launching Version Cue Server Through the IDE Versus Normal Operation . . . . . . . . . . . . . 16
Obtaining Debug Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Stopping Version Cue Server from the IDE of Version Cue SDK . . . . . . . . . . . . . . . . . . . . 20
Checking that Version Cue Server is Running . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Exploring the Version Cue SDK Samples and Documentation . . . . . . . . . . . . . . . . . . . . . 22
Creating your First Plug-in . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Creating a new Version Cue plug-in project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Adding an Extension to the Manifest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Defining a Class for the Listener Extension . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Associating the Listener Extension to its Implementation Class . . . . . . . . . . . . . . . . . . . . 30
Running the Hello World plug-in . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Deploying the Hello World plug-in . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Frequently Asked Questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Why is Version Cue Server the Target Platform for Plug-in Development? . . . . . . . . . . . . . 34
Why is there a full launch/debug configuration category for Version Cue Server? . . . . . . . . 34
Where do I find the Error Log for Version Cue SDK itself? . . . . . . . . . . . . . . . . . . . . . . . . 35
How can I have my plug-in contribute entries to the Version Cue Server log file? . . . . . . . . 35
3
Contents
4 Getting Started with Adobe Version Cue CS3 Development
Getting Started with Adobe Version Cue CS3 Development
Getting Started with Adobe Version Cue CS3 Development
This document describes how to get started with development using the Adobe® Version Cue® CS3 SDK. The target audience for this document is systems integrators who need to develop plug-ins for Adobe Version Cue Server™.

Terminology

The following terms are used throughout this document:
z Eclipse — An integrated development environment (IDE) for Java™ (and other languages)
and a run-time environment for applications. Eclipse-based products, like Version Cue Server, use the Eclipse run-time. The Eclipse run-time starts the Eclipse platform base, and it dynamically discovers and loads (on-demand) plug-ins that make up the Eclipse-based product. Version Cue SDK is another Eclipse-based product, based on the Eclipse work­bench.
Ter mi no lo gy
z Target platform — The platform for which plug-ins are developed, namely Ver sion Cue
Server.
z <vcsdk> — The path to the folder where you installed Version Cue SDK.
z Version Cue SDK — The SDK used to develop plug-ins for Version Cue Server, which also
has resources to help in developing server-driven scripts for Version Cue clients. This is a pre-configured version of Eclipse, branded by Adobe. It has an integrated development environment (IDE) for developing Version Cue Server plug-ins; it includes custom Adobe plug-ins that provide wizards, samples, Help documentation, and additional features to support development of Version Cue Server plug-ins.
z Version Cue Server — The server component of Version Cue CS3.

Introduction

To start developing plug-ins for Version Cue Server, perform these steps:
1. Check that your machine meets the basic requirements specified in “Development Plat-
forms” on page 6.
2. Set up your machine for development; follow the instructions in “Setting up your Develop-
ment Platform” on page 7.
Getting Started with Adobe Version Cue CS3 Development 5
Getting Started with Adobe Version Cue CS3 Development

Development Platforms

3. Examine the documentation: inspect the Samples guide (accessible from the Welcome page), import the samples from the Welcome page, and compile and run them. See
“Exploring the Version Cue SDK Samples and Documentation” on page 22.
4. Write a plug-in by following the instructions in “Creating your First Plug-in” on page 24.
Development Platforms
Platforms supported for Version Cue plug-in development, and required components, are listed in Ta bl e 1 :
TABLE 1 Supported Development Platforms and Required Components
Platform Component Note
Mac OS
10.4 or later
Mac OS 10.4 or later
Versio n Cue Server (3.1.0)
Versio n Cue SDK (1.1.0)
JRE 1.5 You must have JRE 1.5 installed on your machine;
Mac OS 10.3 and earlier are not supported. You must use 10.4 or later as your development platform on the Mac. Both MacTel and PPC are supported.
Install Version Cue Server from an installer; the SDK expects the Server to be located in the fixed install location.
This is based on Eclipse 3.2 Final (29 June 2006), configured with Adobe plug-ins, preferences, and other features to help developing plug-ins for Version Cue Server. You should install the SDK from the installer.
this is the Java run-time environment required to launch Version Cue SDK. If you have been accepting software updates from Apple, this should be installed.
6
Getting Started with Adobe Version Cue CS3 Development
Platform Component Note

Setting up your Development Platform

Windows XP or later (Vista)
XP: Service Pack 1 or higher
Versio n Cue Server (3.1.0)
Versio n Cue SDK (1.1.0)
JRE 1.5 You must have JRE 1.5 installed on your machine,
Version Cue Server must be installed on a local NTFS-formatted drive, not a FAT/FAT32 drive. We recommend you do not install on a mapped network drive.
Install Version Cue Server from an installer; the SDK expects the Server to be located in the fixed install location.
This is based on Eclipse 3.2 Final (29 June 2006), configured with Adobe plug-ins, preferences, and other features to help developing plug-ins for Version Cue Server. You should install the SDK from the installer.
which is the Java run-time environment required to launch the Version Cue SDK; visit http://java.sun.com/downloads/ if you do not have this already. Note that JDK 1.6 is not currently a supported development environment.
Other components you will need to work with the Version Cue SDK are listed in Ta bl e 2 :
TABLE 2 Other Required Components
Component Note
Adobe Reader 7.0 or later This is required to view Adobe PDF documentation.
Adobe Creative Suite® 3 point products
Use point products such as Adobe Bridge™ CS3, Adobe Photoshop® CS3, and Adobe InDesign® CS3 to create and work with content in Version Cue CS3 Server. You must use versions compatible with the Version Cue CS3 Server you are using.
Setting up your Development Platform

Installation and Configuration

Before you Begin

z You will need a Suite installer, which will enable you to install Version Cue CS3 Server.
Please run this Suite installer (to install the Version Cue Server) before installing the Ver­sion Cue SDK. If you do not do this, then you must update your target platform manually from within the IDE of Version Cue SDK.
Getting Started with Adobe Version Cue CS3 Development 7
Getting Started with Adobe Version Cue CS3 Development
Setting up your Development Platform
z It is recommended to use the latest installer for Version Cue SDK (1.1.0 at the time of writ-
ing). If you already have installed Version Cue SDK 1.0.0 (GM), then you should be able to update to Version Cue SDK 1.1.0 by running the latest installer and upgrading your exist­ing SDK.
z You should be sure that your Version Cue Server is upgraded to 3.1.0, which is the version
required for Version Cue SDK 1.1.0. This also requires you to upgrade your Adobe Bridge CS3 application to 2.1 and be sure that Version Cue client libraries are upgraded to 3.1.0.
z You must have at least one point product in Creative Suite CS3 installed, such as Adobe
Bridge CS3, and it should be a build that is known to work with the Version Cue Server you have installed. It is recommended that you have Version Cue SDK 1.1.0, Version Cue Server 3.1.0, Version Cue Client 3.1.0 and Adobe Bridge CS3 2.1.
If you already have Adobe Creative Suite 1 installed, you must remove it, since it is not com­patible with Version Cue CS3. Before removing Adobe Creative Suite 1, export any valuable files stored in Version Cue CS1 to another computer, using the Administration user interface.
If you already have Adobe Creative Suite 2 installed, export any valuable files stored in Version Cue CS2 to another computer and stop Version Cue CS2 (see “Stopping Version Cue CSx” on
page 12).

Installing the Version Cue SDK

You already should have installed Creative Suite CS3, and downloaded Version Cue SDK installer for your platform. To start working with the SDK, follow these steps:
1. It is recommended to upgrade Version Cue Server and Client components to 3.1.0 (the lat­est at the time of writing), and Adobe Bridge CS3 to version 2.1. In this case, you must use Version Cue SDK 1.1.0 (dot release). Note that some of the new samples (sam­ple.remoteproject, for instance) added between Version Cue SDK 1.0.0 and 1.1.0 depend on using Version Cue Server 3.1.0, since there were some additions the API for Version Cue Server 3.1.0.
2. Install Version Cue SDK 1.1.0 (dot release). If you already have installed Version Cue SDK
1.0.0 (GM), then you should be able to update to Version Cue SDK 1.1.0 by simply running the latest installer and choosing the option to update your existing SDK.
3. Install the SDK to a drive with at least 500 MB of free space (and preferably more). On Windows, use an NTFS-formatted drive (not FAT/32 nor a network drive).
4. For the rest of this document, we refer to the folder path containing the installed Version Cue SDK and other components as <vcsdk>. Note that the installer will by default install into these folders:
c:\Program Files\Adobe\Adobe Version Cue CS3 SDK\ (Windows) /Applications/Adobe/Adobe Version Cue CS3 SDK/ (Mac OS)
5. Examine the <vcsdk> folder- its contents are shown Table 3 . Note the PDF documentation is in the sdk.docs folder. Conceptual documentation can also be found under Version Cue SDK Help, along with reference documentation like the server Java API Reference, Exten­sion Point Reference and Client Scripting Reference.
8
Getting Started with Adobe Version Cue CS3 Development
Setting up your Development Platform
TABLE 3 Version Cue SDK Content
Folder/ file name Description
“VersionCueSDK” Folder containing the IDE for Version
Cue SDK, which contains Adobe branding and plug-ins that customize the base Eclipse IDE. Sample plug-ins must be imported from the Welcome page (or mini-Welcome page) via a wizard.
sdk.docs Folder containing conceptual
documentation, such as the PDF documentation in this table. This content also is in the documentation under Versio n Cue SDK > H e lp.
Readme.txt The Readme file for this SDK.
legal Folder containing End-User License
Agreements, as shown by the SDK installer.
sdk.docs/getting-started.pdf This document.
sdk.docs/programmers-guide.pdf Adobe Version Cue CS3 Server
Programmer’s Guide; this is the Version Cue Server guide for this SDK.
sdk.docs/connecting-external-system.pdf Case Study: Connecting to an External
System through Adobe Version Cue CS3. This is based on the reference implementation CustomProject.
sdk.docs/client-programmers-guide.pdf Version Cue CS3 Client Programmers
Guide. Describes the extensibility features at the client enabled by this SDK and working with the scripting interface to Version Cue CS3 clients.

Running Version Cue SDK for the First Time

To run Version Cue SDK initially, follow these steps:
1. Make sure that you have installed Version Cue SDK from the installer, as described above. If you have updated from Version Cue SDK 1.0.0 (GM) to 1.1.0 (dot release), then you should delete the Eclipse workspace you were using previously and start with a clean, fresh Eclipse workspace.
2. Run the Version Cue SDK application in the <vcsdk>/VersionCueSDK folder. During start-up, you should see an Adobe-branded splash-screen.
Getting Started with Adobe Version Cue CS3 Development 9
Getting Started with Adobe Version Cue CS3 Development
Setting up your Development Platform
3. When prompted to select a workspace, choose a new folder, <vcsdk>/workspace, and check “Use this as the default…”.
4. Note that you should look in the "VersionCue.log" created on first startup to confirm there are no errors; if everything is set up correctly, the only information in the log should be that the target platform has been changed correctly. You can find this log file in the Eclipse workspace you choose, in the folder <vcsdk>/workspace/vc-data/logs.
5. From the Welcome screen, you can import sample plug-ins. They are organized into func­tional categories; a sample can fall into multiple categories. Choose one or more categories, and one or more sample plug-ins is imported into your workspace. If you already imported a sample plug-in, you are given the chance to replace it. In Figure 1, samples related to noti­fication will be imported.
6. Verify that you can browse the Version Cue SDK programming documentation from both the Welcome screen and the Help system. To check within the Help system, select Help > Help Contents > Adobe Version Cue SDK Help.
FIGURE 1 ImportingSamples from the Welcome Screen via the Wizard
10
Version Cue SDK sets up the target platform to refer to the Version Cue Server it expects to find in the default installation location for Creative Suite CS3. If you install the Version Cue Server after the SDK, you need to set the target platform manually ; see “Plug-in Development
Target Platform Preferences” on page 10.
Plug-in Development Target Platform Preferences
If you install Version Cue Server and then the SDK, you should not need to change settings related to the target platform, as they are set up automatically by Version Cue SDK. However, if you inadvertently install Version Cue Server after the SDK, then you will need these steps.
To set preferences for the plug-in development target platform, follow these steps:
Getting Started with Adobe Version Cue CS3 Development
Setting up your Development Platform
1. Select Window > Preferences > Plug-in Development > Target Platform. The preferences dialog for the target platform opens.
2. Verify the Location field is set to refer to the installed Version Cue Server. Change it to this path if needed- for instance, if you have installed the Server after the SDK and the target platform is not defined. The installation paths are as follows:
/Library/Application Support/Adobe/Adobe Version Cue CS3/Server/ (Mac OS) C:\Program Files\Common Files\Adobe\Adobe Version Cue CS3\Server\ (Win)
Java Compiler Preferences
This section is for information only. You should not need to change settings related to compiler preferences, as they already are set up for you within the Version Cue SDK IDE.
To set Java compiler preferences, follow these steps:
1. Select Window > Preferences > Java > Compiler,. The preferences dialog for the Java com­piler opens.
2. Verify the option for JDK compliance level is set to 5.0, meaning JDK 1.5.
3. Verify the option “Generated .class files compatibility” is set to 5.0.
4. Verify the option “Source compatibility” is set to 5.0.
From within the IDE, you can switch to the Java perspective by selecting Window > Open Perspective > Java.
Java Installed JREs Preferences
N OTE: Windows: before you can launch Version Cue SDK for the first time, you must have
JRE 1.5 installed on your machine. Once you launch Version Cue SDK, you can switch the JRE preference to the one supplied with the installed Version Cue Server.
1. Select Window > Preferences > Java > Installed JREs. The Installed JREs dialog for the Java compiler opens.
2. Choose the JRE for your platform: On Windows, add the JRE that Version Cue Server uses, in a subfolder “jre” of the installation folder. If you have other JREs installed, they also are listed. Check the box for the Version Cue Server JRE; see Figure 2. On Mac OS, verify you are using the Mac OS JRE 1.5; see Figure 3.
3. The IDE may ask whether you want to do a full rebuild. Answer Yes.
Getting Started with Adobe Version Cue CS3 Development 11
Getting Started with Adobe Version Cue CS3 Development
Setting up your Development Platform
FIGURE 2 Installed JREs Setting on Windows
FIGURE 3 Installed JREs Setting on Mac OS
12

Stopping Version Cue CSx

Before running Version Cue Server, stop any other Version Cue Server(s) running on your local machine. For instance, if you installed Version Cue CS2 as part of Creative Suite CS2, make sure it is turned off.

On Windows

To stop Version Cue CSx on Windows, follow these steps:
Getting Started with Adobe Version Cue CS3 Development
Setting up your Development Platform
1. Open the Version Cue CSx preferences by double-clicking its tray bar icon. The icon for CS2 is a green leaf; for CS3, the icon has changed somewhat and is no longer a leaf. If the icon is not visible, open the Windows control panel and double-click the Adobe Version Cue CSx item.
2. Use Settings > Version Cue CSx to stop the installed server.
3. Uncheck Settings > Turn Version Cue On When Computer Starts, to prevent the installed server from restarting automatically.
4. Click OK to save your changes. Wait until shutdown completes.
5. Verify no instance of a Version Cue Server is running: start the Task Manager by pressing Ctrl-Alt-Del, and choose the Processes tab. For instance, if you stop Version Cue CS2, there should be no instance of the “VersionCueCS2.exe” process. You can leave the Version­CueCSxTray.exe process running. Stopping this process does not stop Version Cue CSx.

On Mac OS

To stop Version Cue CSx on Mac OS, follow these steps:
1. Open the Version Cue CSx preferences window by clicking its menu bar icon and selecting the Version Cue CSx Preferences menu item. The icon for CS2 is a green leaf; for CS3, the icon has changed somewhat and is no longer a leaf. If the icon is not visible, open the Mac System Preferences window and double-click the Version Cue CSx item.
2. Use Settings > Version Cue CSx to stop the installed server.
3. Uncheck Settings > Turn Version Cue On When Computer Starts, to prevent the installed server from restarting automatically.
4. Click Apply to save your changes. Wait until shutdown completes.
5. Verify no instance of a Version Cue Server is running, by using the Activity Monitor. This application normally is in your Applications/Utilities folder. For instance, if you stop Ver­sion Cue CS2, there should be no instance of the “VersionCueCS2” process. You can leave the VersionCueCSxStatus process running. Stopping this process does not stop Version Cue Server.

Stopping the MySQL Database Service

If you started Version Cue Server from Version Cue SDK and have not used the “Shutdown Version Cue Server” button to terminate it (see “Stopping Version Cue Server from the IDE of
Version Cue SDK” on p a g e 20), you will have a MySQL database service running. You need to
terminate this service before re-starting the server.

On Windows

To determine whether MySQL is running, use Task Manager > Processes (look for the mysqld­nt.exe process) or execute the following command from a command line:
telnet localhost 50702
Getting Started with Adobe Version Cue CS3 Development 13
Getting Started with Adobe Version Cue CS3 Development
Setting up your Development Platform
If you see “Connect failed,” terminate the connection with Ctrl-D. If you see anything else, MySQL is running.
To terminate MySQL, open the Task Manager > Processes tab, and terminate the mysqld­nt.exe process.

On Mac OS

To determine whether MySQL is running, use the Activity Monitor. This application normally is in your Applications/Utilities folder.
To terminate MySQL, filter for a process called mysqld, and quit that process.

Preparing to Start Version Cue Server

To configure Version Cue SDK to be able to run Version Cue Server, follow these steps:
1. From within Version Cue SDK, select Window > Open Perspective > Java, to switch to the Java perspective.
2. Select Run > Run, to create a new Version Cue Server configuration.
3. In the Configurations Pane (the left-hand pane), select “Version Cue Server” and click the New Launch Configuration button.
4. Specify “Version Cue Server” as the configuration name.
5. Click Apply, to accept the default settings; see Figure 4.
6. Verify the “Main > Program to Run > Run an application” field contains the following value:
com.adobe.versioncue.tomcat.application
7. Click Close, to complete the “Version Cue Server” configuration.
14
Getting Started with Adobe Version Cue CS3 Development
Setting up your Development Platform
FIGURE 4 Creating a Launch Configuration to Run Version Cue Server

Running Version Cue Server for the First Time

Regardless of how you start Version Cue Server, before you start it for the first time, you must secure the Version Cue Server by navigating to the Administration page and supply a pass­word for the system admin user. By default, the Administration page is http://localhost:3703/. If you do not set a password for the system admin user, you will not be able to connect to your Version Cue Server from any Version Cue client; your Version Cue Server will be invisible to Version Cue clients.

Starting Version Cue Server from the IDE of Version Cue SDK

To run Version Cue Server from within the IDE of Version Cue SDK, follow these steps:
1. From within the IDE, select Window > Open Perspective > Java, to switch to the Java per­spective.
2. Select Run > Run.
Getting Started with Adobe Version Cue CS3 Development 15
Getting Started with Adobe Version Cue CS3 Development
Setting up your Development Platform
3. In the Configurations pane (the left-hand pane), select “Run Version Cue Server.” If you did not yet create the configuration to run Version Cue Server, you will not have a “Run Version Cue Server” configuration. To create it, follow the instructions in “Preparing to
Start Version Cue Server” on page 14.
4. Click the Run button. If the Version Cue Server starts successfully, you should see a series of messages, (which may include non-fatal error messages). The following is an example of the start-up messages:
2006-10-12 ... [main] OFF com.adobe.versioncue.boot - ### Starting Version
Cue® CS3...
2006-10-12 ... [main] OFF com.adobe.versioncue.tomcat - ### Version Cue 3.0 up
and running ###
2006-10-12 ... [VCThreadPool-1] ERROR com.adobe.versioncue.aum - Update Check
failed. Please install Adobe Update Manager.
On Windows, when the server is starting, the Version Cue splash screen should appear briefly. On Mac OS, the splash screen does not display.
A console message within the IDE confirms the server is running. This should look like
Figure 5, although you may see additional, non-fatal errors (as described above) after the
server starts. The figure shows the typical output on starting Version Cue Server from within the IDE of Version Cue SDK.
Note that in addition to the output shown in Figure 5, when you start Version Cue Server without the system admin password set, you will also see warnings that you need to visit the administration interface at http://localhost:3703/ and set the system admin password.
FIGURE 5 Console Output on Starting Version Cue Server within Version Cue SDK
N OTE: To further check the server is running, you should follow the instructions in “Checking
that Version Cue Server is Running” on page 21.

Launching Version Cue Server Through the IDE Versus Normal Operation

Default Port and the Administration Interface

When you run an installed Version Cue Server under control of the IDE of Version Cue SDK, you will notice some differences to when it is running normally, if started through the System Preferences > Version Cue CS3 (Mac) or Control Panel > Version Cue CS3 (Win).
16
For instance, the port number on which Version Cue Server listens by default is 3703 when you launch Version Cue Server under control of the IDE of the SDK; for instance, the adminis-
Getting Started with Adobe Version Cue CS3 Development
Setting up your Development Platform
tration interface would be http://localhost:3703, for the Version Cue Server running on your local machine. You will find that the port Version Cue Server listens on when started as a sys­tem service through the System Preferences (Mac) or Control Panel (Win) is something like 50xxx, and varies dynamically.

Workspaces and Databases

There is another fundamental difference between starting Version Cue Server under control of the IDE of Version Cue SDK, versus starting it through the System Preferences (Mac) or Con­trol Panel (Win). When you create an eclipse-workspace within the IDE of Version Cue SDK, this eclipse-workspace now has its own Server database. In other words, when you start Ver­sion Cue Server under control of the IDE of this SDK, then any information added to the Ver­sion Cue Server is stored in a database that is within your eclipse-workspace folder. If you had already added assets to the Version Cue Server started through the System Preferences (Mac) or Control Panel (Win), then these will not show up under the projects that appear when you browse the Version Cue Server started under control of the IDE.
Vice versa, the database underlying the installed Version Cue Server is not affected when you start Version Cue Server under control of the IDE of this SDK— each eclipse-workspace that you create when using the IDE has its own local database.
Note that a new Version Cue Server database is created within the eclipse-workspace folder when the IDE of this SDK is first started with a clean workspace.
To set up your eclipse-workspace correctly for development within the IDE of this SDK, the Version Cue Server matching the SDK must be installed or must reside as a peer of the Ver­sionCueSDK folder containing the executable for the IDE of this SDK. We strongly recom­mend to install Version Cue Server first and than install the Version Cue SDK.

Obtaining Debug Information

If you started Version Cue Server under control of the debugger (Debug > Version Cue Server), you can view additional debug information, if you set a breakpoint and inspect assets from within the Variables view of the Debug perspective.
The Variables view in the Debug perspective of IDE shows additional information about assets and asset containers. The IDs and URIs of assets, and the IDs, URIs, and children of asset con­tainers are displayed. This is shown in Figure 6.
Getting Started with Adobe Version Cue CS3 Development 17
Getting Started with Adobe Version Cue CS3 Development
Setting up your Development Platform
FIGURE 6 Debug > Variables View, Showing Information for an Asset Identity
Also see the preferences: Java > Debug > Logical Structures. Here you can find the added struc­tures related to the Version Cue Server API.
Figure 7 shows IDE set-up to trace information about SOAP calls and controller calls to the
IDE console, and representative output. This tracing enables you to more easily debug the fol­lowing operations:
z Registration of SOAP methods and types and invocation of SOAP methods.
z Creation and invocation of controller methods (but only for external namespaces).
18
Getting Started with Adobe Version Cue CS3 Development
FIGURE 7 Tracing SOAP Calls and Controller Calls
Setting up your Development Platform
To use this feature, follow these steps:
1. Open (or create) the Version Cue Server launch configuration, as described in “Preparing
to Start Version Cue Server” on page 14.
2. Open the “Tracing” tab.
3. Check “Enable tracing for selected plug-ins.”
4. Select the checkbox for the plug-ins “com.adobe.versioncue.controller.core” (to trace infor­mation about controller calls in external namespaces only) and/or “com.adobe.version­cue.soapdime” (to trace information about SOAP messages for all namespaces).
5. Select the relevant options for those plug-ins.
6. Once you start Version Cue Server, you see log entries like this:
Getting Started with Adobe Version Cue CS3 Development 19
Getting Started with Adobe Version Cue CS3 Development
Setting up your Development Platform
2006-10-12 ... [JobExecutor[shortRunning]-2] OFFcom.adobe.versioncue.soapdime ­Called soap method:http://ns.adobe.com/workgroup/asset/3.0/#exploreAssets 2006-10-12 ... [JobExecutor[shortRunning]-2] OFFcom.adobe.versioncue.controller.core - Created: class'sample.customproject.AssetController' namespace: 'ns.sample.customproject' 2006-10-12 ... [JobExecutor[shortRunning]-2] OFFcom.adobe.versioncue.controller.core - Invoke: class'sample.customproject.AssetController' method: 'explore' namespace:'ns.sample.customproject'

Stopping Version Cue Server from the IDE of Version Cue SDK

To stop Version Cue Server from within the Version Cue SDK IDE, use the “Shutdown Ver­sion Cue Server” button, shown in Figure 8. This button appears to the left of the Debug icon.
FIGURE 8 Shutdown Version Cue Server Button
This stops both Version Cue Server and its MySQL database service in one step.
Alternatively, you can stop Version Cue Server and its MySQL database service in two steps, as follows:
1. Stop Version Cue Server by clicking the Terminate button (red square), in either the Con­sole or Debug view. See Figure 9. If Version Cue Server failed to start properly for any rea­son, this button is not enabled.
2. Stop the MySQL database service; see “Stopping the MySQL Database Service” on page 13 or “On Mac OS” on page 14.
20
Getting Started with Adobe Version Cue CS3 Development
FIGURE 9 Terminate Button, Console, and Debug View
Setting up your Development Platform

Checking that Version Cue Server is Running

To verify the server is running, follow these steps:
1. Open http://localhost:3703 in a browser.
2. If the server is running, the Version Cue Administration login web page is displayed.
Figure 10 shows how the Administration interface appears when running Version Cue
Server for the first time.
Getting Started with Adobe Version Cue CS3 Development 21
Getting Started with Adobe Version Cue CS3 Development
Setting up your Development Platform
FIGURE 10 Version Cue Administration Login Web Page
N OTE: The Administration interface should look similar but not identical to that shown
above, due to late-breaking changes. However, the functionality exposed to the user should be equivalent to that shown above.

Exploring the Version Cue SDK Samples and Documentation

Prerequisites

Before exploring SDK documentation, ensure that you:
z Set up your development environment as described in “Setting up your Development Plat-
form” on page 7.
z Have a working knowledge of Java and some idea of how to develop plug-ins for an
Eclipse-based product.

Samples

Samples Guide
Samples are documented in the Samples Guide, which is in Version Cue SDK under Help > Help Contents > Adobe Version Cue SDK Help. A Samples Overview page can be accessed directly from the Welcome page, which lists summaries of all the samples and enables you to access the more detailed documentation for each sample.
22
Getting Started with Adobe Version Cue CS3 Development
Setting up your Development Platform
Automatically Importing Samples from the Welcome Page
Sample projects are in the folder structure of an Adobe plug-in. Version Cue SDK samples can be imported from the Welcome page, using a wizard that automates the import of the samples. You already may have imported some or all of the samples, as the Welcome page is one of the first views you see when you open the Version Cue SDK.
On the Welcome page, click on a category to import the samples; one or more sample plug-ins should be imported into your workspace. See Figure 1, where the option to import samples that extend the Version Cue client user interface was chosen.
Manually Importing Samples
We strongly recommend you not import samples manually but instead use the wizard to import samples via the Welcome page. If you want to import the sample projects manually, follow these steps:
1. Locate compressed forms of the samples in the following folder, and uncompress them prior to import:
<vcsdk>/VersionCueSDK/plugins/com.adobe.versioncue.sdk.samples_3.0.0/samples
2. Select File > Import > General > Existing Projects into your workspace, and import the samples you require.
3. Select the projects you want to import.
4. Select Finish. You should now see one or more projects imported into your workspace.
Although Version Cue SDK is set up to build the projects automatically (if the Project > Build Automatically menu element is checked), you may have to manually clean up and then trigger a complete rebuild to eliminate some compile errors. Ideally, there should be no compile errors or warnings.
Running Samples
The instructions for running sample plug-ins are like those described in “Running the Hello
World plug-in” on page 31. The Samples Guide has instructions specific to each sample. You
can browse this guide from within Version Cue SDK; see Help > Help Contents > Adobe Ver­sion Cue SDK Help.
Deploying samples
The instructions for deploying sample plug-ins are like those described in “Deploying the
Hello World plug-in” on page 32.

API Reference and Other Documentation

After you follow the instructions in this guide, the API Reference is available from the context of Version Cue SDK Help. You can navigate to the API Reference via Help > Help Contents > Adobe Version Cue SDK Help > References. You also will find other useful material, such as the Extension Points Reference and the Scripting Interface Reference.
Getting Started with Adobe Version Cue CS3 Development 23
Getting Started with Adobe Version Cue CS3 Development

Creating your First Plug-in

Creating your First Plug-in
This section describes how to write a plug-in that extends Version Cue Server in a very basic way. The instructions create a Hello World plug-in, which writes a message to the console whenever asset content is stored on (uploaded to) a Version Cue Server.

Prerequisites

Before starting, ensure that you:
z Set up your development environment as described in “Setting up your Development Plat-
form” on page 7.
z Have a working knowledge of how to use an Eclipse-based SDK to develop plug-in projects
in Java.

Overview

These are the high-level steps to create and run a HelloWorld plug-in for Version Cue Server:
1. “Creating a new Version Cue plug-in project” on page 24.
2. “Adding an Extension to the Manifest” on page 27.
3. “Defining a Class for the Listener Extension” on page 28.
4. “Running the Hello World plug-in” on page 31.
5. “Deploying the Hello World plug-in” on page 32.
These steps create a plug-in project called com.yourco.versioncue.helloworld, which contains a package of the same name. Throughout these instructions, we use com.yourco as a placeholder for a namespace of your choice. For example, if your company controls the widgetcom­pany.co.uk domain, you might want to use uk.co.widgetcompany in place of com.yourco.

Creating a new Version Cue plug-in project

To create a new Version Cue plug-in project, follow these steps:
1. Select Window > Open Perspective > Other and choose Plug-in Development. See
Figure 11.
2. From the IDE of Version Cue SDK, select the item New > Project > Version Cue Plug-in Development > Version Cue Plug-in Project. See Figure 12.
24
3. Click Next and proceed to the next screen.
4. Uncheck “Use default location.”
Getting Started with Adobe Version Cue CS3 Development
Creating your First Plug-in
5. Assign a “Project name.” It is good practice to use namespaces in your Java code from the outset, and to reflect the main namespace in the project name; in this example, com.yourco.versioncue.helloworld.
6. Use the Browse button to create a new folder for the project, called <vcsdk>/projects.
7. Set Directory: <vcsdk>/projects/com.yourco.versioncue.helloworld
8. Click Next and proceed to the next screen. See Figure 13.
9. By default, Plug-in Version is set to 1.0.0. The Plug-in Version is independent of the Ver­sion Cue Server version, and you can choose the version number you want to use here.
10. You can set Plug-in Name: HelloWorld Plug-in
11.You can set Plug-in Provider to something appropriate. In practice, we expect you to set this to your company name.
12.Check the box “Registering Listener...” to add some plug-in dependencies.
13.Click Finish to dismiss the dialog, and accept the suggestion to open the Java perspective when you have dismissed the dialog.
14. The plug-in you have created is now functional and potentially could be loaded as-is, but we will be adding a listener for an event associated with an asset being added or a version saved to Version Cue Server in the next section.
FIGURE 11 Selecting the Plug-in Creation Wizard
Getting Started with Adobe Version Cue CS3 Development 25
Getting Started with Adobe Version Cue CS3 Development
Creating your First Plug-in
FIGURE 12 Creating a New Version Cue Plug-in Project
FIGURE 13 Finishing the New Version Cue Plug-in Project Wizard
26
Getting Started with Adobe Version Cue CS3 Development

Adding an Extension to the Manifest

To add a listener, follow these steps:
1. In the Plug-in Manifest Editor, double-click MANIFEST.MF and open the Extensions sec­tion. Alternatively, the Overview page describing the plug-in— the first thing you see after creating the new plug-in— has a pane entitled Extensions; click on the Extensions link and you will open the Extensions section.
2. Click the Add... button you see on the Extensions section.
3. Select com.adobe.versioncue.controller.core.listener. See Figure 14.
4. Click Finish.
5. Use File > Save to save your edits. Make sure your edits were saved. If there is an asterisk to the left of the filename in the editor tab, the file was not saved.
FIGURE 14 Selecting an Extension Point
Creating your First Plug-in
Getting Started with Adobe Version Cue CS3 Development 27
Getting Started with Adobe Version Cue CS3 Development
Creating your First Plug-in

Defining a Class for the Listener Extension

This section describes how to define the Java class for a listener extension. The class writes a message to the console each time asset content is stored (uploaded) to Version Cue Server; that is, whenever a new file-based asset is added to a project on the Version Cue Server or a new version of an existing asset is created.
To define the Java class for a listener extension, follow these steps:
1. In the Package Explorer, right-click the com.yourco.versioncue.helloworld package, and use New > Class to create a new Java class for your listener implementation. See Figure 15.
2. Under Name, enter StoreContentListener.
3. Under Superclass, enter com.adobe.versioncue.controller.asset.api.events.StoreContentLis­tenerAdapter. Alternatively, click on the Browse button to the right of the Superclass edit box, enter a few characters like Sto and then you will see the choices for the superclass. See Help > Version Cue SDK > API Reference for documentation on the class StoreCon­tentListenerAdapter.
4. Click Finish.
5. Define a preCall method that writes “HelloWorld” to the console. The code required is shown in Example 1.
6. Use File > Save to save your edits. Make sure your edits were saved. If there is an asterisk to the left of the filename in the editor tab, the file was not saved.
28
Getting Started with Adobe Version Cue CS3 Development
FIGURE 15 Creating a NewClass named StoreContentListener
Creating your First Plug-in
EXAMPLE 1 StoreContentListener.java Class for HelloWorld
package com.yourco.versioncue.helloworld; import org.eclipse.core.runtime.IProgressMonitor; import com.adobe.versioncue.controller.asset.api.events.StoreContentListenerAdapter; import com.adobe.versioncue.controller.asset.api.events.IStoreContentEvent; import com.adobe.versioncue.core.VersionCueException; /** * Writes a message to the console when notified that asset content is being * stored. */ public class StoreContentListener extends StoreContentListenerAdapter {
/** */ public void preCall(IProgressMonitor monitor, IStoreContentEvent event) throws VersionCueException { System.out.println("HelloWorld..."); }
}
Getting Started with Adobe Version Cue CS3 Development 29
Getting Started with Adobe Version Cue CS3 Development
Creating your First Plug-in

Associating the Listener Extension to its Implementation Class

To connect the listener extension to its implementation class, follow these steps:
1. In the Plug-in Manifest Editor, double-click MANIFEST.MF to open the Extensions sec­tion.
2. Right-click on extension com.adobe.versioncue.controller.core.listener. See Figure 16.
3. Select New > assetStoreContentListener to define the controller event of interest as asset content being stored.
4. Click the Browse button to choose the implementation class.
5. Under Select, enter com.yourco.versioncue.helloworld.StoreContentListener.
6. Click OK.
7. Use File > Save to save your edits and complete the extension definition, as shown in
Figure 17. Make sure your edits were saved. If there is an asterisk to the left of the filename
in the editor tab, the file was not saved.
FIGURE 16 New > assetStoreContentListener extension
30
Getting Started with Adobe Version Cue CS3 Development
Creating your First Plug-in
FIGURE 17 Completed Listener Extension Definition
Your plugin.xml file contains the element that maps the extension to its implementation class, as shown in Example 2.
EXAMPLE 2 plugin.xml Extension Definition, on Adding assetStoreContentListener
<plugin> <extension point="com.adobe.versioncue.controller.core.listener"> <assetStoreContentListener class="com.yourco.versioncue.helloworld.StoreContentListener"/> </extension> </plugin>

Running the Hello World plug-in

If you followed the procedures in the preceding sections, your project should resemble that shown in Figure 18.
FIGURE 18 The Completed Project
To build and run your plug-in under Version Cue Server while working in the IDE of Version Cue SDK, follow these steps:
Getting Started with Adobe Version Cue CS3 Development 31
Getting Started with Adobe Version Cue CS3 Development
Creating your First Plug-in
1. In the IDE of Version Cue SDK, select Window > Open Perspective > Java, to switch to the Java perspective.
2. Build the project from within Version Cue SDK. It may be built already, if “Build Automat­ically” is enabled (its default state) on the Project menu.
3. Run Version Cue Server from within the IDE of Version Cue SDK. See “Starting Version
Cue Server from the IDE of Version Cue SDK” on page 15.
4. Confirm Version Cue Server is running. See “Checking that Version Cue Server is Run-
ning” on page 21.
5. Use a Version Cue client for CS3, such as Adobe Bridge CS3, to add a file to a project on your Version Cue Server. Alternatively, add a new asset— or version of an existing one— by running code snippets CreateProject and CreateFile from sample.snippetrunner, with default arguments. The sample.snippet plug-in can be imported to your workspace by clicking the “Get started ...” sample category on the Welcome screen.
6. In response to the operation to add a file to the project— a “store-content” operation— the plug-in writes a message to the console like that shown in Figure 19.
FIGURE 19 Console Message Written by your Plug-in

Deploying the Hello World plug-in

To build your plug-in as a JAR file and deploy it so Version Cue Server can run it, follow these steps:
1. Stop the installed Version Cue Server, through the System Tray icon (Windows) or Control Panel (Mac OS).
2. Select File >Export.
3. Select Plug-in development > Deployable plug-ins and fragments.
4. From the list of Available Plug-ins and Fragments, select the newly created plug-in project, com.yourco.versioncue.helloworld.
32
5. Use Export Destination > Directory > Browse to set the export path for the plug-in. Choose <installdir>/Server; the export itself will deploy to the plugins folder within the chosen folder.
Getting Started with Adobe Version Cue CS3 Development

Troubleshooting

6. Note that <installdir> represents the location where Version Cue Server is installed:
c:\Program Files\Adobe\Adobe Version Cue CS3 SDK\ (Windows) /Applications/Adobe/Adobe Version Cue CS3 SDK/ (Mac OS)
7. Click Finish to complete the export.
8. Verify that the <installdir>/Server/plugins folder to which you exported the plug-in con­tains the following file:
com.yourco.versioncue.helloworld_1.0.0.jar
9. Start the installed Version Cue Server, through the System Tray icon (Windows) or Con­trol Panel (Mac OS). Note that you must have already stopped the Version Cue Server from the IDE of Version Cue SDK, if it was already started from the IDE.
10.Use Adobe Bridge CS3 or another Creative Suite CS3 application to add a file to a project on your Version Cue Server. In response to this operation, the plug-in will write a message to the log-file of Version Cue Server.
N OTE: If your plug-in implements a Web application extension and has Java Server Pages
(JSP), the plugin should not be exported as a JAR file, because the JSP files cannot be compiled in this stage. If you have JSP files, verify that Export Options > Package plug­ins as individual JAR archives is unchecked, and export your plug-in to a folder.
Troubleshooting
Ta bl e 4 lists issues that may be encountered in developing Version Cue SDK sample plug-ins,
and it suggests possible resolutions.
TABLE 4 Troubleshooting Version Cue SDK Sample Plug-ins
Issue Resolution
Version Cue Server fails to start under control of the IDE, with this error: IllegalStateException:Unable to start
database....
Version Cue Server fails to start under control of the IDE, with this error: FATAL com.adobe.versioncue.core ­Aninstance of VC Server is already running using this workspace.Failed
to start Version Cue CS3 Server....
Version CueR CS3 shut down.
An instance of the MySQL database service may be running already. Stop MySQL; see “Stopping the MySQL Database Service” on page 13. Note that in more recent versions of the SDK, this message has been replaced.
This is the error message that is shown when you try to start a Version Cue Server using the same workspace/database as the one that is already running. You should shut down the existing Server- for instance, if you started the running one under control of the IDE, then use the button to Shut Down Version Cue Server. Alternatively, if the Server was started through the Control Panel (Windows) or System Preferences (Mac), then stop the Server through the same mechanism.
Getting Started with Adobe Version Cue CS3 Development 33
Getting Started with Adobe Version Cue CS3 Development

Frequently Asked Questions

Issue Resolution
Version Cue Server fails to start, with this error: org.osgi.framework.BundleException
When you try and start Version Cue Server as described in “Starting
Version Cue Server from the IDE of Version Cue SDK” on page 15, an
instance of Eclipse workbench starts instead of Version Cue Server
Version Cue Server fails to start, with this error: “java.net.BindException: Address already in use: JVM_Bind:3703”
Version Cue Server fails to start under control of the IDE, with warning about logs/VersionCue.log
A Java run-time environment (JRE) matching the Version Cue Server needs to be configured. Set a JRE under Java > Installed JREs; see “Java
Installed JREs Preferences” on page 11.
Most likely, the target platform preference was not set correctly when you configured to launch Version Cue Server. Switch to the Java perspective. Use Run > Run to open the configuration dialog. In the left­hand pane, choose the configuration named “Run Version Cue Server.” If the configuration exists, click the Delete button to delete it. Click Close to dismiss the dialog. Follow the procedures in “Plug-in
Development Target Platform Preferences” on page 10 followed by “Preparing to Start Version Cue Server” on page 14, and you should be
able to start Version Cue Server from the Version Cue SDK IDE.
An instance of Version Cue Server already is running; for instance, is Version Cue CS2 Server running? Alternatively, you may have an instance of Version Cue CS3 Server already running- perhaps started from the Control Panel on Windows or System Preferences on Mac OS.
This can happen if you installed Version Cue SDK before the Version Cue Server was installed, and you already started Version Cue SDK without the Server being installed. Later, on installing the Server, the workspace that you were using initially is corrupt and you must either delete the workspace folder or delete all its contents.
34
Frequently Asked Questions

Why is Version Cue Server the Target Platform for Plug-in Development?

Version Cue Server is based on Eclipse’s universal plug-in architecture, PDE. Although Ver­sion Cue Server is not an IDE in the traditional sense, it is an Eclipse environment and can be extended using the Eclipse plug-in architecture. For more information, see Adobe Version Cue CS3 Server Programmer’s Guide (programmers-guide.pdf).
Why is there a full launch/debug configuration category for Version Cue
Server?
In most cases, one configuration suffices; however, many developers prefer to have multiple configurations, supporting different trace settings and so on.
Getting Started with Adobe Version Cue CS3 Development
Frequently Asked Questions

Where do I find the Error Log for Version Cue SDK itself?

You can find a file named VersionCue.log, which should be created in the Eclipse workspace you have chosen; for instance, <vcsdk>/workspace/vc-data/logs/VersionCue.log. You will find this contains information above and beyond what is shown in the Console window.
How can I have my plug-in contribute entries to the Version Cue Server log
file?
Version Cue Server uses the logging framework log4j, and your plug-in can contribute entries to the log file, if you have a file called log4j.properties in the server configuration folder with the appropriate key-value pairs to enable logging for the packages in your plug-in. You will find that there is a sample named sample.customproject in this SDK that has a custom log4j.properties, to enable logging of warnings and errors in that sample to the Version Cue Server log.
If you are running Version Cue Server under control of the IDE of the Version Cue SDK, you can enable logging of information from your own plug-in to the Version Cue Server logfile, if you copy your own custom log4j.properties file to the folder <your-workspace>/vc-data/con­fig/ and restart Version Cue Server.
When Version Cue Server is started through the Control Panel (Windows) or System Prefer­ences (Mac), you must copy your custom log4j.properties file to the folder <Version Cue/Server>/config, where <Version Cue/Server> represents the path to your installed Ver­sion Cue Server. This will enable logging of information for the sample.customproject directly into the Version Cue Server log file.
Any key defined in your log4j.properties file will be appended to the Version Cue logger con­figuration. If a property has already been defined, then the existing value will be overridden by the value supplied in your log4j.properties file. Below is an example of adding a key-value pair to a custom log4j.properties file.
# Print only messages of level WARN or above in the package sample.customproject. log4j.logger.sample.customproject=WARN, LOGFILE
Note that overriding the default Version Cue logger settings, such as the LOGFILE.layout, may affect the log being displayed in the Administration user interface of Version Cue Server. For more information on log4j, such as what keys and values you can have in your log4j.properties file, see the log4j documentation, available at http://logging.apache.org/log4j/docs/index.html
Getting Started with Adobe Version Cue CS3 Development 35
Getting Started with Adobe Version Cue CS3 Development
Frequently Asked Questions
36
Loading...