Macromedia Version Cue - CS3 Programmer's Guide
ADOBE VERSION CUE CS3
SERVER PROGRAMMER’S GUIDE
© 2007 Adobe Systems Incorporated. All rights reserved.
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.
Contents
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
3
Contents
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
4 Adobe Version Cue CS3 Server Programmer’s Guide
Adobe Version Cue CS3 Server Programmer’s Guide
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 “Extension 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.
Introduction
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 workbench.
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 development 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 5
Adobe Version Cue CS3 Server Programmer’s Guide
Version Cue Architecture
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 workgroup, 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 Programmer’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.
6
Adobe Version Cue CS3 Server Programmer’s Guide
FIGURE 1 Version Cue Architecture
Version Cue Architecture
Version Cue Client
Machine
boundary
(Bridge)
SOAP
Version Cue Server
Version Cue Client
(Photoshop)
SOAP
Database
Web browser client
Machine
boundary
HTTP
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 provide. 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 different Version Cue clients share code for processing SOAP messages within the Version Cue protocol, 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 Version Cue Server; see “Version Cue Server Extensibility” on page42 and the Extension Point
Reference.
Adobe Version Cue CS3 Server Programmer’s Guide 7
Adobe Version Cue CS3 Server Programmer’s Guide
Version Cue Architecture
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 efficiently, 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 capture, 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 messages 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 communication 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
8
Adobe Version Cue CS3 Server Programmer’s Guide
FIGURE 2 Version Cue Server Layered Architecture
Version Cue Server
Protocol manager
Supports communication with Version
Cue Clients using protocols such as SOAP
and HTTP
Controller
Encapsulates the normal business logic of Version Cue,
such as exploring projects, exploring assets and
searching for assets.
Version Cue Architecture
Model
Business objects in the model layer represent
entities such as assets, versions and projects.
Persistence
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.
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.
Adobe Version Cue CS3 Server Programmer’s Guide 9
Adobe Version Cue CS3 Server Programmer’s Guide
Version Cue Architecture
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. Transactions 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 architecture. 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
SOAP request
SOAP response
Protocol
manager
create-project
identity of
project created
Controller PersistenceModel
start
transaction
create
project
IProject created
end
transaction
10
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 subinterfaces 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 11
Adobe Version Cue CS3 Server Programmer’s Guide
Version Cue Architecture
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 transaction—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 listener 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 critical section. The first to acquire the mutex proceeds to execute in the critical section, whilst the
other thread is blocked.
12
Adobe Version Cue CS3 Server Programmer’s Guide
FIGURE 4 Conceptual Threading Model for Version Cue Client
Version Cue Architecture
explore-assets
Version Cue Client
operations
critical-section
send SOAP
request
«blocking-receive»
handle SOAP response
get-preview
network
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
sent back to the Client
process SOAP
request
(server)
Send
SOAP
response
then
display-assets
display-preview
Adobe Version Cue CS3 Server Programmer’s Guide 13
Adobe Version Cue CS3 Server Programmer’s Guide
Version Cue Architecture
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 clients 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.
14
Adobe Version Cue CS3 Server Programmer’s Guide
FIGURE 5 Sequence Diagram Showing Requests and Thread Pools
Version Cue Architecture
Admin Web UI TomcatClient
SOAP request
JSP req ue st, long-running operation
:HTTP connector
get con necto r
run
get con necto r
run
«th read»
invo ke
Short-running
thread pool
get free Job
invo ke
threa d pool
run
get free Job
run
«thread»
:Job
invo ke method
invo ke method
:ControllerCa llLong-running
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 component 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 scheduled 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 database; for instance, a job can encapsulate a read-only request. the job executor uses two jobrelated thread pools:
Adobe Version Cue CS3 Server Programmer’s Guide 15
Adobe Version Cue CS3 Server Programmer’s Guide
Version Cue Architecture
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[shortRunning]...” 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 pending 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 completed; 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 database 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 concurrency 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 concurrency 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 transaction is aborted. In this case, an OptimisticLockException is thrown, indicating an unusually
high load on the Version Cue Server.
16
Adobe Version Cue CS3 Server Programmer’s Guide
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 Version 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.
Version Cue Architecture
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 thumbnails, 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 17
Adobe Version Cue CS3 Server Programmer’s Guide
Version Cue Architecture
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 Administration user interface or server-internal processes.
You must be aware of generation flags when you implement an asset-view factory; for example, when connecting to an external system. See “Influencing how Assets Display at the Client
via Asset-view Factory” on page57.
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 following:
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 Version 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 discover what has changed at the Version Cue Server.
18
Typically, a Version Cue client performs a call to explore assets within a particular asset container 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
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 version), 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 19
Adobe Version Cue CS3 Server Programmer’s Guide
Version Cue Server Model
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 specific 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 Client 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
20
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 relationships that exist between them. The description is given at a fairly abstract level. For exam-
Adobe Version Cue CS3 Server Programmer’s Guide
ples of the business objects in a project containing a variety of files and folders, see “Sample
Version Cue Server Model” on page 33.
All business objects in the Version Cue Server model are subinterfaces of IModelObject. A
business object with this IModelObject interface has a persistent footprint in the database
associated with Version Cue Server; see Figure 1. A business object has an identifier that is
unique within the Version Cue Server scope; see “Identifiers” on page 31.
Assets, Asset Containers, and Asset Hierarchy
The class diagram in Figure 6 shows inheritance relationships for interfaces representing assets
and containers. Note the following:
z Asset containers are themselves assets.
z All assets have some kind of identity associated with them, through the IAssetIdentity
superinterface. This identity has a namespace. The namespace identifies a notional set, of
which the asset is a member. See “Namespaces” on page 32.
z Assets and asset containers are persistent model objects (IModelObject instances). The per-
sistent state of assets, asset containers, and the hierarchical relationships between them are
stored in the database.
Version Cue Server Model
FIGURE 6 Inheritance for Asset and Asset Container
IModelObject IAssetIdentity
IAsset
IAssetContainer
The class diagram in Figure 7 shows the fundamental relationship between asset container and
asset. Asset containers contain assets and have a parent-child relationship.
Adobe Version Cue CS3 Server Programmer’s Guide 21
Adobe Version Cue CS3 Server Programmer’s Guide
Version Cue Server Model
FIGURE 7 Asset Containment
IAssetContainer
1parent
0..*child
IAsset
An asset container owns a collection of assets and knows about its immediate children. Each
asset knows its parent. Asset containers also are assets; therefore, asset containers can contain
other asset containers and form an asset hierarchy.
The recommended method to traverse an arbitrary asset hierarchy is to use an asset visitor
(IAssetVisitor), an instance of the Visitor design pattern (Gamma et al., 1995). You implement
IAssetVisitor, and then your code can ask a particular IAsset to accept your asset visitor. Your
IAssetVisitor implementation is called when each node is visited in the hierarchy, descending
from the asset that accepted the visitor.
Projects
The class diagram in Figure 8 shows inheritance relationships for interfaces representing
projects
FIGURE 8 A Project and its Root Containers
IProject IAssetContainer
1
has root containers
1..*
IRootContainer
A Version Cue project is an asset hierarchy. The root of the hierarchy is an IProject instance,
the project root node. A project is an asset container. The direct children of a project must be
IRootContainer subinterfaces.
22
The asset hierarchy of a project can be traversed from root to leaf, or leaf to root. You can navigate from the root node to a leaf node through IAssetContainer, or you can navigate from a
leaf node through IAsset to the project root node (IProject).
Each project has as its immediate children a set of root containers holding different asset types.
These root containers must be subinterfaces of IRootContainer. For example, file assets are
contained by a file root container (IFileRootContainer). There are other specialized root con-
tainers for entities such as collections; see “Other Asset Types” on page 30.
The root containers are the immediate children of a project in the asset hierarchy. They exist
only at this level; that is, they are never at deeper levels in the asset hierarchy.
Files and File Containers
The class diagram in Figure 9 shows the association between project and file root container.
Both are asset containers. A project has a file root container, invariably named “files,” containing the asset hierarchy for files.
FIGURE 9 A Project and the Root Container for Files
Adobe Version Cue CS3 Server Programmer’s Guide
Version Cue Server Model
IProject
1
has root container named files
1
IFileRootContainer
IAssetContainer
IRootContainer
The class diagram in Figure 10 show inheritance relationships between interfaces corresponding to asset containers, file containers, and files. The asset hierarchy under a file root container
contains files and file containers. A file container is an asset container that happens to hold
files. A file container also is an asset (IAsset); therefore, a file container can hold other file containers, in a recursive association.
Adobe Version Cue CS3 Server Programmer’s Guide 23
Loading...