Adobe Version Cue CS3 User guide

ADOBE VERSION CUE CS3

SERVER PROGRAMMER’S GUIDE

Adobe Version Cue CS3 Server Programmer’s Guide

Technical note #10301

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.

3

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Terminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Version Cue Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

Client-Server Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

Extensibility Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

Layered Architecture. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

Threading Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

Flags and the Version Cue Protocol. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Project Capabilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

Version Cue Server Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

Business Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

Assets, Asset Containers, and Asset Hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

Projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

Files and File Containers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

Users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

Versions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

Version Metadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Locks. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

Asset Metadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

Other Asset Types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

Identifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Internal URIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Namespaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

Asset and Version Identities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

Asset Views. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

Sample Version Cue Server Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

Empty Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

One Version of a File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

File Being Edited . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

Two Versions of a File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

Two Versions of a File Plus a Folder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

Contents

4 Adobe Version Cue CS3 Server Programmer’s Guide

Version Cue and the Development Platform. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

Eclipse, Version Cue Server, and Version Cue SDK. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

Plug-ins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

Extension Points and Extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

Version Cue Server Extensibility. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

Overview of Integrating with Version Cue Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

Notification about Controller Events and the Controller Listener . . . . . . . . . . . . . . . . . . . 42

Intercepting Controller Events with a Valve . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

Transaction-related Events and the Unit-of-Work Listener . . . . . . . . . . . . . . . . . . . . . . . 49

Notification Sequence for Valves and Listeners . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

Supporting Dynamic Pages with a Web Application . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

Customizing Controller Logic to Connect to External Systems. . . . . . . . . . . . . . . . . . . . . 54

Customizing Icons for Assets. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

Influencing how Assets Display at the Client via Asset-view Factory . . . . . . . . . . . . . . . . . 57

Adding to the Administration Interface and Plug-in Admin . . . . . . . . . . . . . . . . . . . . . . 60

Contributing Client Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

Customizing the Capabilities (Function) of a Project . . . . . . . . . . . . . . . . . . . . . . . . . . . 66

Extending the Version Cue SOAP protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66

User Creation, Login and Authorization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

Appendix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69

Additional Version Cue Server Model Diagrams. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69

Bibliography . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71

Adobe Version Cue CS3 Server Programmer’s Guide 5

Adobe Version Cue CS3 Server Programmer’s Guide

Introduction

Adobe Version Cue CS3

Server Programmer’s Guide

Introduction

This document is for system integrators developing plug-ins for Adobe® Version Cue® Server™.

Version Cue Server is an Eclipse-based product. Integrating with Version Cue Server entails

writing Java™-based plug-ins. We introduce some of the published extension points of Version

Cue Server and how to take advantage of them; they are described in more detail in the “Exten-

sion Point Reference.”

The architecture of the Adobe Version Cue client is documented in more detail in the “Client

Programmer’s Guide.” That document describes how to integrate with and extend the Version

Cue client via JavaScript and other resources sent from Version Cue Server to the client.

Terminology

The following terms are used throughout this document:

z Adobe Bridge® — Adobe Bridge CS3, a particularly privileged Version Cue client.

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.

z Host name — The name of the machine running the Version Cue Server, as it appears in the

Version Cue client.

z Version Cue client — The client component of Version Cue CS3. This is any point product

in Adobe Creative Suite® 3, which is integrated with the Version Cue client shared libraries,

such as Adobe InDesign® CS3, Adobe Bridge CS3.

z Version Cue SDK — The SDK used to develop plug-ins for Version Cue Server. This is a

pre-configured, Adobe-branded version of Eclipse. It includes custom Adobe plug-ins that

provide wizards, samples, Help documentation, and additional features to support devel-

opment of Version Cue Server plug-ins.

z Version Cue Server — The server component of Version Cue CS3.

z Version Cue Server plug-in — A plug-in developed in Java using the Version Cue SDK, con-

forming to the pattern required to be loaded and called by Version Cue Server.

Adobe Version Cue CS3 Server Programmer’s Guide

Version Cue Architecture

6

Version Cue Architecture

Client-Server Overview

Version Cue CS3 is a component of Adobe Creative Suite 3, which provides revision control

for files directly from the point products in Adobe Creative Suite. It also provides workflow

management features, such as a check-out/check-in protocol for working with files in a work-

group, directly accessible from the user interface of the point products in Adobe Creative

Suite. Version Cue Server is the server component of Version Cue.

Version Cue client products, such as Adobe Bridge CS3, communicate with Version Cue

Server primarily using SOAP or HTTP. In this document, we focus mainly on Version Cue

Server. The architecture of Version Cue clients is described in more detail in the “Client Pro-

grammer’s Guide.”

Figure 1 shows the major architectural components of Version Cue. The Version Cue Server

and client components may run on separate machines. The client is integrated into Adobe

point products within Adobe Creative Suite via the Version Cue client libraries. Version Cue

Server is a database-centric application: it uses an underlying database to store its persistent

data, including metadata about assets. This database and its organization are proprietary and

not directly accessible from the published API of Version Cue Server.

Adobe Version Cue CS3 Server Programmer’s Guide 7

Adobe Version Cue CS3 Server Programmer’s Guide

Version Cue Architecture

FIGURE 1 Version Cue Architecture

If you write a single, Java-based plug-in for Version Cue Server, point products in Creative

Suite 3 that are integrated with Version Cue can take advantage of the functionality you pro-

vide. This means there is a single point of extensibility for Adobe Creative Suite, which avoids

the need to write multiple plug-ins for different plug-in architectures if you program to the

“native” (e.g., C++) API of each client application.

Version Cue clients (such as Adobe Photoshop) use SOAP to communicate with Version Cue

Server. The Web Administration user interface uses HTTP to communicate with Version Cue

Server. The Version Cue client shared library is used by the point products. This means differ-

ent Version Cue clients share code for processing SOAP messages within the Version Cue pro-

tocol, and they do not have to implement their own SOAP stacks. This SOAP stack is not

available for your use directly through the published API of Version Cue, although you can

extend the set of SOAP messages used to communicate between Version Cue client and Ver-

sion Cue Server; see “Version Cue Server Extensibility” on page 42 and the Extension Point

Reference.

Version Cue Client

(Bridge)

Version Cue Client

(Photoshop)

Web browser client

Version Cue Server

Database

Machine

boundary

Machine

boundary

HTTP

SOAP

Adobe Version Cue CS3 Server Programmer’s Guide

Version Cue Architecture

8

Extensibility Basics

Version Cue Server is an Eclipse-based product, and it uses the Eclipse run-time and plug-in

architecture. Extensibility at the server is based on the extension-point architecture of Eclipse.

Among other benefits, this means at run-time, Version Cue Server can load plug-ins effi-

ciently, as it uses the “lazy” class-loading mechanism of Eclipse. Version Cue Server uses

Apache Tomcat as an application server; for example, as a servlet/JSP engine, to handle HTTP

requests or create dynamic HTML pages or RSS feeds.

Client extensibility for CS3 is performed by sending resources from Version Cue Server to the

Version Cue client. Client extensibility is achieved mainly through server-driven scripts (and

other resources) from server plug-ins, rather than programmers having to deploy distinct

scripts through another mechanism (e.g., as part of an installation procedure) at each client.

You can customize and extend aspects of the Version Cue client user interface and its logic

from Version Cue Server, by sending JavaScript fragments and other resources from Version

Cue Server to the client. For example, you may want to add custom user-interface elements to

the Adobe Common User Interface (CUI), such as a custom dialog to enforce metadata cap-

ture, along with your own validation logic.

Layered Architecture

Basic Layering Model

Version Cue Server has a layered architecture, as shown in Figure 2. Version Cue clients send

SOAP request messages over HTTP to Version Cue Server and receive SOAP response mes-

sages in reply. The Web Administration user interface sends HTTP requests from a Web

browser client to Version Cue Server and receives HTTP responses in reply. These are dealt

with by the protocol manager layer. The protocol manager layer is responsible for communi-

cation with Version Cue clients; it interacts with the controller layer. Once the controller layer

executes its business logic, the protocol manager creates response messages and sends them

back to the Version Cue clients.

Each layer is described in a subsequent section:

z “Protocol Manager Layer” on page 11

z “Controller Layer” on page 11

z “Model Layer” on page 12

z “Persistence Layer” on page 12

Adobe Version Cue CS3 Server Programmer’s Guide 9

Adobe Version Cue CS3 Server Programmer’s Guide

Version Cue Architecture

FIGURE 2 Version Cue Server Layered Architecture

Much of the normal Version Cue business logic is encapsulated in the controller layer. Version

Cue business objects (and associated logic) are defined in the model layer; this includes

projects, assets, and versions. See “Version Cue Server Model” on page 20. Business objects

have a persistent representation in the database, encapsulated within the persistence layer.

Version Cue Server

Protocol manager

Controller

Persistence

Supports communication with Version

Cue Clients using protocols such as SOAP

and HTTP

Encapsulates the normal business logic of Version Cue,

such as exploring projects, exploring assets and

searching for assets.

Business objects in the model layer represent

entities such as assets, versions and projects.

Initiates transactions to allow updating of

business objects in the model layer and

persists the state of business objects

(including their metadata) to the database.

Model

Adobe Version Cue CS3 Server Programmer’s Guide

Version Cue Architecture

10

Changes to business objects must occur within the scope of transactions. The controller layer

cooperates with the persistence layer to make changes to business objects. The persistence

layer provides transaction support and communicates with the underlying database. Transac-

tions either commit the changes to the model to the underlying database or roll-back in the

case of an error. The controller layer updates business objects in the model layer, always within

the scope of transactions.

We can consider a fundamental operation, like creating a new project on a Version Cue Server,

to illustrate how the components interact; in particular, how messages proceed through the

layers of the Version Cue Server architecture. Figure 3 is a conceptual view of the message

sequence that occurs when a new project is created, through the different layers of the archi-

tecture. In this case, the client requests creation of a new project. The client sends a request to

Version Cue Server, which is handled by the protocol manager. To create a new project, the

protocol manager calls the project controller. The project controller calls the persistence layer,

to start a transaction on the database. (A transaction is started only when the model is updated;

read-only operations on the model do not initiate a transaction.)

FIGURE 3 Sequence Diagram for Creating a New Project

Version Cue

Client

Protocol

manager

Controller PersistenceModel

SOAP request

create-project

start

transaction

create

project

IProject created

end

transaction

identity of

project created

SOAP response

Adobe Version Cue CS3 Server Programmer’s Guide 11

Adobe Version Cue CS3 Server Programmer’s Guide

Version Cue Architecture

In the context of a transaction, the project controller manipulates the business objects in the

model layer. These objects have a persistent footprint in the database system, managed

through the persistence layer.

For instance, if the request is to create a new project, and the project controller successfully

creates a project, the controller returns the (asset) identity of the new project to the protocol

manager. On success, the project controller calls the persistence layer to end the transaction

(task); on failure, it rolls back the incomplete effects of the transaction. The protocol manager

sends a status message to the client, indicating the outcome of the controller operation.

Protocol Manager Layer

The protocol manager supports interaction with Version Cue clients. A Version Cue client

using SOAP makes what is effectively a remote procedure call to the Version Cue Server. The

protocol manager parses the incoming message and delegates to the controller execution of the

operation. The protocol manager then creates a response message based on the result of the

controller call and sends this to the client. This was shown in Figure 3.

Controller Layer

The controller layer is responsible for the core logic of Version Cue Server. The controller

layer has diverse capabilities, including the following:

z Initiating transactions on the database

z Optimistic lock handling

z Parameter validation

z Processing list calls (a form of batch processing)

z Checking that users have appropriate access rights to execute operations and error han-

dling

z Error handling

z Committing transactions or rolling back

The main function of the controller layer is delivered by individual controllers, which are sub-

interfaces of IController. These controllers encapsulate normal Version Cue business logic.

The controller layer cooperates with the persistence layer to make changes to business objects

safe and secure. When a request to create a project is received, the controller layer initiates a

transaction using the persistence layer and creates a business object (the new project) in the

model layer.

In practice, the controller layer has specialized components that deal with operations on

projects, assets, locks, and metadata, and operations like searching. For example, the operation

to create a new project is executed by the project controller.

When creating a new project, the project controller validates the inbound parameters and, if

validation succeeds, calls the persistence layer to start a transaction. A new business object is

created, which has a persistent representation in the database. The results of the operation are

propagated to the protocol manager layer, which creates a response message and sends this to

the Version Cue client. This was shown in Figure 3.

Adobe Version Cue CS3 Server Programmer’s Guide

Version Cue Architecture

12

Model Layer

The model layer represents business objects within the Version Cue domain, such as projects,

assets, versions, and metadata; see “Version Cue Server Model” on page 20. When extending

Version Cue Server, you must change business objects in the model layer from within a trans-

action—and, ideally, using a pre-existing controller method—for instance, from the scope of a

listener, when observing a controller event that is already updating the business objects in the

model layer. You cannot change the state of business objects directly from the context of a lis-

tener which is notified on a read-only call of the model. See the Extension Point Reference

(Version Cue SDK > Help) for an indication of whether listeners are notified in the scope of a

read-only or update call.

If your code is not running in the scope of a transaction, business objects should be changed

only through an appropriate controller API method. See the API Reference for more details on

the xxx.controller.xxx.api packages

The controller layer uses the persistence layer to start transactions on the underlying database,

which persists the state of the business objects.

Persistence Layer

The persistence layer is responsible for persisting the state of business objects in the model

layer. The state of these objects is stored in the underlying database. The controller layer

depends on the persistence layer to start transactions and allow it to safely update the state of

business objects in the model layer.

In the event of errors in performing the updates within a transaction, the persistence layer can

roll back changes to business objects in the model layer, so incomplete effects of an operation

do not persist. This is fundamental to maintaining the integrity of Version Cue Server data.

The persistence layer uses optimistic locking: different database transactions can read the same

state concurrently, and data integrity is checked only on a database write.

Threading Model

Version Cue Client and Multi-threading

Version Cue clients are Adobe applications that are integrated with the Version Cue client

libraries. The Version Cue client library has a multi-threaded core, but sending and receiving

SOAP messages is serialized. Although a single Version Cue client can have multiple threads

executing the library code, only one of its threads is sending/receiving at any time.

The critical section in the client is protected by a synchronization object—a “baton” or mutex.

In a relay race, even if there are four runners in the team, only one at a time can hold the baton,

and similarly for running threads and the mutex. Figure 4 shows two hypothetical requests,

both of which try to acquire the mutex synchronization object that protects access to the criti-

cal section. The first to acquire the mutex proceeds to execute in the critical section, whilst the

other thread is blocked.

Adobe Version Cue CS3 Server Programmer’s Guide 13

Adobe Version Cue CS3 Server Programmer’s Guide

Version Cue Architecture

FIGURE 4 Conceptual Threading Model for Version Cue Client

network

critical-section

explore-assets

get-preview

display-assets

display-preview

send SOAP

request

process SOAP

request

(server)

«blocking-receive»

handle SOAP response

Send

SOAP

response

Version Cue Client

operations

Version Cue Server: performs

server-side processing to

handle the SOAP request

from the Version Cue Client,

obtain a list of assets given

request parameters (or

preview of those assets) and

create SOAP response given

the request, which is

then

sent back to the Client

Adobe Version Cue CS3 Server Programmer’s Guide

Version Cue Architecture

14

The thread executing in the critical section sends a SOAP request, receives a SOAP response

(or a time-out period is exceeded, if there is network congestion or a Version Cue Server is

unavailable), and then leaves the critical section, releasing the mutex. The next thread acquires

the mutex, enters the critical section, sends the SOAP request, waits for a SOAP response (or

time-out period), and so on.

A Version Cue client issues only one SOAP request at a time; however, multiple Version Cue

clients (such as Adobe Bridge and Adobe Photoshop) on one machine can issue concurrent

requests to the Version Cue Server. Also, there can be multiple machines with Version Cue cli-

ents issuing concurrent requests to one Version Cue Server. To ensure responsiveness at each

client, the Version Cue Server must support a reasonably high degree of request concurrency.

Version Cue Server and Request Concurrency

The Version Cue Server can process up to 75 concurrent requests from clients. Each request is

processed in a separate thread. The model of one-thread-per-request is bounded by the upper

limit on the size of the thread pool. These threads handle requests coming in from Version

Cue clients (SOAP requests) or from the Administration user interface (HTTP requests).

Some of the key concepts about the threading model of Version Cue Server are as follows:

z Version Cue Server can process concurrent requests from Version Cue clients, which come

in as SOAP requests over HTTP.

z Version Cue Server has thread pooling, which can be configured through the Administra-

tion user interface.

z There are several thread pools: one belonging to the HTTP Connector (running within

Tomcat) and two belonging to the job-handling component (Job Executor threads).

z The minimum number of connector threads is 5; maximum, 75.

z Every client request runs in its own thread of execution. The thread associated with a client

request belongs to Connector thread pool.

z The thread associated with a transaction is started from a connector thread and belongs to

the Job Executor thread pool.

z The Context instance you get using Context.currentContext() belongs to the current thread

in which a transaction is executing; it is a ThreadLocal variable.

z Every transaction is executed in the Context from which it was started.

z Every database transaction has a one-to-one association with a thread in the Job Executor

pool.

Figure 5 shows the conceptual (forward) message flow between components, when requests

come in from a Version Cue client over SOAP, and from the Web-based Administration user

interface over HTTP. Most of the objects shown in the figure are in the protocol manager layer

of the Version Cue Server architecture. To simplify the diagram, return messages are omitted.

Adobe Version Cue CS3 Server Programmer’s Guide 15

Adobe Version Cue CS3 Server Programmer’s Guide

Version Cue Architecture

FIGURE 5 Sequence Diagram Showing Requests and Thread Pools

Both SOAP and plain HTTP requests are processed initially by a component running within

Tomcat. Tomcat is an application server for Version Cue Server; the HTTP connector compo-

nent runs within Tomcat and maintains the connector thread pool. This connector thread

pool contains 5 – 75 threads, which are used to service requests that come in via SOAP

requests (bound to HTTP) and normal HTTP requests; for instance, from the Administration

user interface. The size of this thread pool can be configured through the Administration user

interface itself or the Version Cue Server global preferences file, VersionCueSettings.xml.

When viewed in the Version Cue SDK debugger, the threads in the connector thread pool

have names like “Thread [http3703-processor ...] ...”

Each client request is encapsulated in a job. A job contains a task to be performed and is sched-

uled and run by the job executor. Job handling is about supporting concurrent requests at the

Version Cue Server. A single job may or may not lead to a transaction on the underlying data-

base; for instance, a job can encapsulate a read-only request. the job executor uses two job-

related thread pools:

«thread»

:HTTP connector

«thread»

:Job

:ControllerCallLong-running

thread pool

Short-running

thread pool

Admin Web UI TomcatClient

SOAP request

get connector

run

invoke

get free Job

run

invoke method

JSP request, long-running operation

get connector

run

invoke

get free Job

run

invoke method

Adobe Version Cue CS3 Server Programmer’s Guide

Version Cue Architecture

16

z A short-running tasks thread pool, for tasks expected to be relatively short in duration,

which run synchronously. The threads in this pool are named “[Job Executor[shortRun-

ning]...” and can be viewed in the Version Cue SDK debugger.

z A longer-running tasks thread pool, for tasks expected to take a longer time, which run

asynchronously and can be associated with a progress monitor. The threads in this pool are

named “[Job Executor[longRunning]...”.

Within the handling of a job, when the job takes longer than about three seconds, a job pend-

ing status is returned to the Version Cue client. The job pending status object contains

progress information, which lets the client accurately reflect how much of the job has com-

pleted; for example, in a progress monitor widget shown to the end user.

Not all SOAP requests result in a transaction on the underlying database; for example, they

may be read-only calls at the controller level. See the Extension Point Reference under the

com.adobe.versioncue.controller.core.listener extension point, for information about whether

controller calls are read-only.

If it is not a read-only request, a SOAP request is processed in a thread from one of the job

executor pools, which invokes a controller call and then a transaction on the underlying data-

base in another thread of execution. There is one thread per transaction on the underlying

database.

The context you get using Context.currentContext() is a ThreadLocal variable, which belongs

to the current thread and is associated with a single request. Every transaction runs within the

context from which it was started.

The thread-pooling architecture is based on the work of Doug Lea (Lea, 2005), whose concur-

rency utilities are incorporated into JDK 1.5 through JSR166 “Concurrency Utilities.”

Caveats and Guidance for Thread-safety

The transaction on the database underlying Version Cue Server cannot be used over more

than one thread, and this should not be attempted. For example, if you were to start a new

thread, open a transaction on the underlying database, and continue processing the data

affected by the transaction in a different thread of execution, this pattern would fail. You must

be very cautious about creating new threads from the context of a valve or listener, as you

already have a distinct thread of execution within which the request is being processed.

We recommend you try to use the existing thread pools if you need to create new threads for

your own business logic, but you are not prevented from creating your own thread, such as

worker threads.

Optimistic Locking

Each transaction runs in its own thread, and an optimistic locking scheme controls concur-

rency and ensures the conditions for serializability are met when transactions are executed

concurrently. If a transaction has problems completing, owing to the unavailability of

resources needed to lock for modifications, three retry attempts are made before the transac-

tion is aborted. In this case, an OptimisticLockException is thrown, indicating an unusually

high load on the Version Cue Server.

Adobe Version Cue CS3 Server Programmer’s Guide 17

Adobe Version Cue CS3 Server Programmer’s Guide

Version Cue Architecture

Flags and the Version Cue Protocol

There are two key types of flags in the Version Cue protocol: filter flags (see “Filter Flags” on

page 17) and generation flags (see “Generation Flags” on page 18). Filter flags are sent as part

of a request by a Version Cue client, to modulate the response sent back by the Version Cue

Server. Generation flags are created for each asset by a Version Cue Server, sent back initially

by Version Cue Server and then returned by the Version Cue client in subsequent requests

related to the same assets.

The Version Cue client and Version Cue Server use filter and generation flags to minimize the

amount of data that needs to be transferred between them, while keeping the client and Ver-

sion Cue Server states synchronized. The overall sequence of events is as follows:

1. The Version Cue client receives all current generation flags for an asset as part of every

message response sent back by Version Cue Server. As a result, the client can determine

whether each asset at the client side is up to date.

2. The filter flags enable the Version Cue client to communicate to Version Cue Server the

subset of the data in which they are interested, to restrict the information returned by the

Server.

3. The Version Cue client provides Version Cue Server with all current client-side generation

flags in each request. Version Cue Server sends only filter-requested data which is outdated

at the client.

4. If the Version Cue client does not send a generation flag for a particular asset, Version Cue

Server is forced to send the data without any check to see if the client-side data is up to date.

This can be important for the client, when the client needs to have the content in any event;

for example, if the user made local edits to a document and wants to revert.

Filter Flags

Filter flags are a key part of the Version Cue protocol for communication between the Version

Cue Server and Version Cue client. These flags modulate a client’s request, to specify that a

subset of all possible information about an asset or version should be returned.

The filter flags mechanism gives the Version Cue client the opportunity to obtain exactly the

data needed for a particular context. For instance, if the client is in a mode showing thumb-

nails, it sends the ‘thumbnail’ filter to get the required data back from Version Cue Server. If

the end user switches back to a different view like “details,” this thumbnail information is no

longer needed, and the thumbnail filter is no longer sent.

You need to be aware of filter flags when implementing an asset-view factory. See “Influencing

how Assets Display at the Client via Asset-view Factory” on page 57.

The Version Cue client can send filter flags as part of its SOAP request message to Version Cue

Server, to request that particular information be included in the response message. The filter

flags are interpreted within the protocol manager layer of Version Cue Server. The contents of

the SOAP response message sent back to the client depend on these filter flags; for example,

one of the flags can be “icon,” which means asset representations returned should include an

icon.

Adobe Version Cue CS3 Server Programmer’s Guide

Version Cue Architecture

18

NOTE: The set of filter flags is in the IAssetViewSections interface.

Generation Flags

Generation flags are sent from Version Cue Server to the Version Cue client, to indicate that

persistent data has changed in Version Cue Server. This may be caused by an update operation

on the Version Cue Server triggered by other clients; for example, an operation in the Admin-

istration user interface or server-internal processes.

You must be aware of generation flags when you implement an asset-view factory; for exam-

ple, when connecting to an external system. See “Influencing how Assets Display at the Client

via Asset-view Factory” on page 57.

Generation flags indicate some information about an asset or version that has changed at the

Version Cue Server end. This is similar to the eTag concept in the HTTP 1.1 protocol, applying

not only to content but other data and metadata about an asset.

When an asset or version changes—for instance, when the XMP metadata for a version is

changed—the generation number changes. A generation flag is specific to one aspect of one

asset or version; that is, a given asset has different generation flags for aspects such as the fol-

lowing:

z Content

z XMP metadata

z Thumbnails

A generation flag is a formatted string of the form “X-Y,” where X and Y are two generation

numbers, or integer values that carry information about the state at the Version Cue Server of

assets and versions. Generation numbers are stored along with the assets on the Version Cue

Server. Rules associated with generation flags are described in “Signalling Changes in Assets

and Versions with Generation Flags” on page 19.

When the generation flags are received by the Version Cue client, the client can determine

whether an asset has changed in some respect on the Version Cue Server. The client saves the

flag when it receives the actual data. Later, the client compares this flag to the current Version

Cue Server flag and can determine if an asset is still up to date at the client.

Generation flags also are sent by a Version Cue client to the Version Cue Server, which lets Ver-

sion Cue Server determine whether the client state is out of date with respect to Version Cue

Server. The client sends the last set of generation flags for a set of assets it received from the

Version Cue Server. If a client does not send generation flags, Version Cue Server sends back

data

Typically, clients implement a caching policy, to reduce the amount of redundant data that

needs to be transmitted—perhaps over the network—between Version Cue client and Version

Cue Server. The generation flags are used as part of this caching policy, so the client can dis-

cover what has changed at the Version Cue Server.

Typically, a Version Cue client performs a call to explore assets within a particular asset con-

tainer on a regular basis; that is, polling the Version Cue Server. For instance, calls to explore

assets are issued by a client when the Open dialog is visible. On each request, the client sends a

Adobe Version Cue CS3 Server Programmer’s Guide 19

Adobe Version Cue CS3 Server Programmer’s Guide

Version Cue Architecture

set of filter flags to the Version Cue Server; the set of filter flags is mostly fixed for a specific

view.

Clients not only send filter flags to Version Cue Server with each request (to modulate the

information sent back by Version Cue Server), they also send back the generation flags they

received previously from Version Cue Server. The policy is that the Version Cue client must

send all generation flags for assets associated with every operation it asks Version Cue Server to

perform. This policy enables Version Cue Server to determine whether the client state is out of

date with respect to the Version Cue Server state. When the Version Cue Server determines

that the generation flags are out of sync for a given set of assets, the Version Cue Server sends

back the set of assets, if it was requested explicitly through the filter flags. Otherwise, no data is

transferred for the set of assets, because the Version Cue Server determines that the client

cache is synchronized with the Version Cue Server state.

Version Cue clients save the generation flags (typically in memory) for each asset in projects

that were explored. If the generation flags are returned by the server, the client checks to see if

their local assets are now out of date. If the local data at the client is out of date with respect to

the Version Cue Server, the client can trigger a cascade of explore operations, to synchronize

the data with the state of projects at the Version Cue Server. It is up to the client when to

refresh its local data and how far to explore the assets within projects to regain a synchronized

state.

In more detail, the Version Cue client ignores the generation number if it is less than or equal

to the last saved value. The data returned by the Version Cue Server is discarded, and the client

user interface is not changed.

If the generation number is greater than the last saved value at the Version Cue client, the data

is accepted by the client, and the user interface may be updated, if the data was requested.

The relationship between filter flags and generation flags is as follows: the client sets a filter flag

for aspects of assets (or versions) on which they want to synchronize. The Version Cue Server

sends back the data specified in the filter flags with the response. If the client explicitly

requested relatively large amounts of data (say, XMP-based data), it is returned if it is different

than what the client already has, given the generation flags the client sent. For performance

reasons, data about an aspect is returned only if requested via the filter flags; this is the primary

intent of the filter flags. Even if requested by the filter flags, the Version Cue Server sends back

the data only when the appropriate generation flag that belongs to a filter section also has

changed.

Version Cue Server, however, sends back generation flags for all aspects of the asset (or ver-

sion), regardless of how the filter flags were set. This is so the client can determine if some

other aspect of the asset (or version) changed.

Signalling Changes in Assets and Versions with Generation Flags

The primary purpose of generation flags is to signal change in an asset or a version. We can

consider changes in information that happen at the level of assets and of versions:

Adobe Version Cue CS3 Server Programmer’s Guide

Version Cue Server Model

20

z Asset-level information includes basic information about an asset, such as its name, asset-

level metadata (see “Asset Metadata” on page 29), current head version and content.

z Version-level information includes thumbnails and XMP metadata. See “Version Meta-

data” on page 27.

The generation flag is a formatted string of the form “X-Y,” where X and Y represent 32-bit

integers, separated by exactly one “-” (hyphen) character.

When an aspect of one asset is changing at the asset level—for instance, some asset metadata is

changing—the following rules apply to the generation flag:

z X is constant for one asset identity.

z Y is strictly monotonically increasing.

When an aspect of a version is changing at the version level—for instance, a new thumbnail was

set for one version—the following rules apply to the generation flag:

z X is constant for changes on the same version.

z Y is strictly monotonically increasing.

When a new version of a file is created, the following rules apply to the generation flag:

z X is strictly monotonically increasing on different versions of the same asset,

z Y is reset to an initial value (“0” or “1”) for every new version.

Suppose Version Cue client has a saved generation flag, P, for a specific asset, obtained when it

last synchronized on an asset. Suppose further that the client receives a new generation flag, Q,

from Version Cue Server. The policy at the client to determine whether an asset is out of date

is that it checks to see if the generation flag changed, compared to the one it saved for the spe-

cific asset. In other words, if P and Q are identical, the client recognizes that the asset has not

changed at Version Cue Server.

Project Capabilities

You can customize the capabilities of Version Cue projects; for instance, to add or remove

functionality. You can do this using an extension point concerned with project capabilities; see

“Customizing the Capabilities (Function) of a Project” on page 66. Also see“Contributing Cli-

ent Resources” on page 63 for more information about customizing project capabilities; for

example, disabling selected menu items for a particular project.

Version Cue Server Model

Business Objects

The Version Cue Server model provides the business objects that underlie Version Cue. The

following sections describe the interfaces that characterize the business objects and the rela-

tionships that exist between them. The description is given at a fairly abstract level. For exam-

Page is loading ...

Adobe Version Cue CS3 User guide

Adobe Version Cue CS3 User guide

Related papers

Other documents