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
Adobe Version Cue CS3 Server Programmer’s Guide
Version Cue Server Model
FIGURE 10 Inheritance for Files and File Containers
IAsset
IFileItem
IAssetContainer
IFileContainerIFile
The class diagram in Figure 11 shows the relationships between file containers and files. The
file root container named “files” is the root of the asset hierarchy for files. It is a direct child of
the project root node (IProject). The Composite design pattern (Gamma et al., 1995) is the
model the asset hierarchy follows.
FIGURE 11 File-Container Associations
IFileRootContainer
IAssetContainer 1
1
24
has file
containers
IAsset 0..*
0..*
IFileContainer
1
IAssetContainer 1
has folders
has
files
IAsset 0..*
IFile
has files
0..*
Adobe Version Cue CS3 Server Programmer’s Guide
Version Cue Server Model
Note that folders (IFileContainer instances) and files (IFile instances) can be direct children of
the file root container in a Version Cue CS3 project.
NOTE: In Version Cue CS2, all folders in the project had to be descendants of a “documents”
file container, not peers of it. Also in Version Cue CS2, it was not possible to store files
as direct children of the file root container; files had to go into the predefined file
container named “documents.” This restriction is lifted in Version Cue CS3. By default,
the “documents” folder does not exist in Version Cue CS3 projects.
NOTE: Projects created by Adobe GoLive CS2 have additional file containers named “web-
content,”web-data,” and “web-settings” within their file root container. The web-data
and web-settings folders may become web-content children in subsequent versions of
Adobe GoLive.
The associations shown in Figure 11 as dotted lines between the file root container, file containers, and files are, strictly speaking, instances of the more abstract asset containment association, shown in Figure 12. The associations shown as dotted lines in both Figure 11 and
Figure 12 depend on the asset containment relationship; also see Figure 7.
FIGURE 12 File-Container Relationships
has file
containers
IAssetContainer
1
parent
child 0..*
IAsset
IAssetContainer 1
has folders
IAsset 0..*
IFileContainer
0..*
IAssetContainer 1
1
IFileRootContainer
has files
IAsset 0..*
IFile
IRootContainer
1
has files
0..*
IVersionableAsset
Asset containers maintain the asset hierarchy in a project and represent containers such as the
project itself and folders (containing files and other folders), which cannot be versioned. On
the other hand, files can be versioned, as they are versionable assets, described in “Versions” on
page 26.
Adobe Version Cue CS3 Server Programmer’s Guide 25
Adobe Version Cue CS3 Server Programmer’s Guide
Version Cue Server Model
Users
Version Cue users can log into a Version Cue Server and, once logged in, perform certain
functions for which they are given access. When a user logs in, he must authenticate against
some authenticator. Once logged in, the user can be authorized (allowed access) to perform a
range of functions offered by Version Cue Server. A user is represented by an instance of
IUser.
Users can be considered internal or external. An internal user is a user of a standard Version
Cue project. Log-on (authentication) for this user is handled by the normal business logic of
Version Cue Server. There is an optional configuration in which the user logging on is authenticated against an LDAP server; the server to use is configured through the standard Administration user interface of Version Cue Server.
During login, users may be required to authenticate against some external system that is not
simply an LDAP server. This scenario is significant when you are integrating with Version Cue
to connect Creative Suite to some external system, such as an external digital asset management system. There are extension points that allow you to take control when user instances are
being created, and control how the authentication process occurs and the properties of users
once they are created. These extension points are described in “Version Cue Server Extensibil-
ity” on page 42 and the Extension Point Reference.
Versions
Access Control
Individual users can be assigned to groups (IGroup), and groups can have access rights; for
example, administrators. A user also can be assigned a particular role (IRole) within a project;
for example, project administrator.
Permissions can be set at the asset level; the concept of access rights to assets is based on the
idea of a principal to which access rights are assigned. Within the Version Cue model, a principal can be a user, group or role. The principal can be one of {“administrator”, “owner”, “creator”, “all”}; see SecurityIdentifier.
The principal (user, group, or role) can either have an access right or not (be denied). The
access right can be scoped to be specific to the asset, its children, or all its descendants. The set
of permissions is {“read”, “write”, “delete”}. See PermissionSet.
Assets that can have one or more versions are called versionable assets. Files (instances of IFile)
are versionable assets. There is at least one version of a file, and a new version is created when
end users check in an asset from clients like Adobe Photoshop.
Figure 13 shows the association between a versionable asset (IVersionableAsset) and version
(IVersion). The association between assets and versions is maintained by the IVersionableAsset interface.
26
FIGURE 13 Version Relationships
Adobe Version Cue CS3 Server Programmer’s Guide
Version Cue Server Model
IFile
1
1..*
IVersion
IAssetIVersionableAsset
IModelObject
IVersionIdentity
Only versionable assets can have one or more versions. The Version Cue Server model does
not have versionable assets other than files (IFile instances). Most assets cannot be versioned.
For instance, you cannot version a file container, because although a file container is an asset
container (hence an asset), a file container is not a versionable asset.
Versions have an identity associated with them; see IVersionIdentity. This identity has a
namespace, which identifies a notional set, of which the version is a member; see
“Namespaces” on page 32.
NOTE: A versionable asset and a version have a “has a” relationship rather than an “is a”
relationship. A version (IVersion) is not a type of asset (that is, it is not a subinterface of
IAsset).
Version Metadata
Figure 14 shows interfaces involved with version metadata, which can be broken down into
the following:
z Metadata that can be embedded in XMP. See “XMP Metadata” on page 28 and API Refer-
ence > IXMPMetadata.
z Thumbnails. See “Thumbnails” on page 29 and API Reference > IThumbnail.
z Version-specific properties. See “Version-specific Properties” on page 29 and API Refer-
ence > IVersionProperty.
Adobe Version Cue CS3 Server Programmer’s Guide 27
Adobe Version Cue CS3 Server Programmer’s Guide
Version Cue Server Model
FIGURE 14 Inheritance for Version Metadata
IModelObject
IThumbnailIXMPMetadata
IModelObjectProperty
IAssetVersionProperty
Figure 15 shows metadata associated with a version (IVersion). Note that updating the meta-
data for a particular version creates a new version.
FIGURE 15 Version and Version Metadata Associations
IVersion
1
0..2
IThumbnail IXMPMetadata IAssetVersionProperty
1
0..1
1
0..*
28
XMP Metadata
A version can have XMP metadata associated with it; see Figure 15. The Adobe XMP metadata
packet, which can be embedded within the file, is extracted when a version of a file is saved to
Version Cue Server; for example, through a check-in operation. The XMP-specific metadata is
accessed through the IXMPMetadata interface.
The Adobe XMP format is an XML-based specification for metadata in publishing; see
http://www.adobe.com/xmp for more information. An XMP metadata packet can contain
information related to workflow automation, job processing, and media rights management,
as well as thumbnails of the asset at a particular version. These thumbnails are embedded in
the XMP itself.
Locks
Adobe Version Cue CS3 Server Programmer’s Guide
Version Cue Server Model
Thumbnails
A version can have zero or more thumbnails (IThumbnail); see Figure 15. Thumbnails are
renditions of the asset at that version at a given resolution and in a given format, such as JPEG.
Version-specific Properties
A version can have arbitrarily many properties associated with it; for example, a label or access
rights. These are key-value pairs stored as instances of IVersionProperty; see Figure 15. Unlike
XMP metadata, this type of metadata typically is not embedded in the file for an asset.
Projects can be configured to allow exclusive locks on an asset to be acquired; in such a project,
when an asset is checked out for edit, the asset becomes exclusively locked. When an asset is
exclusively locked on the Version Cue Server, no other users of the project can check out the
same asset for edit until the lock is released or cancelled.
If a project is not configured to allow exclusive locks to be acquired on assets, multiple end
users can check out for edit the same asset at the same time, and a new version is created of the
asset each time the asset it checked in.
Figure 16 shows the relationship between asset and lock: if an asset is checked out for edit, a
lock is associated with it. The lock can be exclusive or shared, and it can apply only to the asset
or include children or other descendants, if the asset is a container.
FIGURE 16 Lock Associations
If a lock is set on a versionable asset, such as a file (IFile instance), a working copy of the asset is
generated. When this happens, all subsequent uploads from the Version Cue client are stored
in that working copy, until the lock is released. When the lock is released, the working copy
becomes the new head revision of the asset.
Asset Metadata
IAsset
1
0..1
ILock
Assets can have metadata associated with them, stored as a collection of asset properties.
Figure 17 shows the association between asset and property. This type of metadata is different
Adobe Version Cue CS3 Server Programmer’s Guide 29
Adobe Version Cue CS3 Server Programmer’s Guide
Version Cue Server Model
than version-specific metadata, such as XMP metadata and thumbnails, described in “Version
Metadata” on page 27.
FIGURE 17 Asset-level Property Associations
Other Asset Types
IAsset
1
0..*
IAssetProperty
A project contains more than files and folders. For instance, when renditions are created for an
asset, these are stored in a specialized root container, which is a child of the project in the asset
hierarchy.
Some of the root containers in a project are shown in the object diagram in Figure 18. Each
root container has a name, such as “files” or “collections,” which forms the first part of the
internal URI (Uniform Resource Indicator) for assets in the container.
FIGURE 18 A Project and Some of its Root Containers
Land :IProject
IProject.getRootContainer
alternates collections ...other root
files renditions
containers...
30
Identifiers
The Version Cue Server model includes the following types of identifiers:
z Model object identifier: An identifier for a persistent model object. This is an IModelObject
z GlobalID: An identifier for a persistent model object, which in theory is at least globally
z Internal URI: Hierarchical names locate a file or folder in a Version Cue project, which fol-
Adobe Version Cue CS3 Server Programmer’s Guide
Version Cue Server Model
instance. The identifier is unique within the scope of a single Version Cue Server. A model
object identifier does not change if a file or folder is renamed in a project. Instances of IModelObject in the Version Cue Server model have this identifier; see IModelObject.getId().
The integer 1001 is an example of a model object identifier.
unique. This consists of the Version Cue Server identifier plus the model object identifier.
A GlobalID does not change if a file or folder is renamed. Instances of IModelObject in the
Version Cue Server model have this identifier; see IModelObject.getGlobalID(). An example of a GlobalID is as follows:
dde0801b-db5a-134a-9841-fc4a172e5c42_3_1
low the RFC 2396. The URI includes the project name and the root container type within
the project. The internal URI changes if a file or folder is renamed. All assets in the Version
Cue Server model have this identifier; see IAssetIdentity.getURI(). An example of an internal URI is as follows:
files:///myproject/myimage.psd
Internal URIs
Projects have an asset hierarchy, and each asset has a unique location in the hierarchy,
expressed as an absolute pathname. This is referred to as the internal URI (Uniform Resource
Indicator) for the asset. The URI depends on what the root container holds. For instance, all
assets in the file root container hierarchy have a URI beginning with “files:///”.
URIs for Projects, Files, and Folders
The internal URI is used primarily to specify the path to locate files and folders within a
project. Once you know the URI of a file or folder, you can navigate through the project to
locate that file or folder, using IAssetContainer.
z Let <project-name> stand for the name of a Version Cue project. The URI of the project
itself is written as:
z The file root container has the following URI:
z Let <folder-name> be an arbitrary folder name. A folder at the root level within the project
(a child of the file root container) has a URI as follows:
project:///<project-name>
files:///<project-name>/
files:///<project-name>/<folder-name>/
Adobe Version Cue CS3 Server Programmer’s Guide 31
Adobe Version Cue CS3 Server Programmer’s Guide
Version Cue Server Model
z Let <image-name> be an arbitrary image name. An image in the <folder-name> folder has
a URI like this:
files:///<project-name>/<folder-name>/<image-name>
To make this concrete, consider assets in a project that has a folder at the root level and a file at
the root level of the project. Consider creating a project named Land, with a folder rivers and a
single file at the root level called “hill.jpg”.
The URI of the “hill.jpg” image in the “Land” project is as follows:
files:///Land/hill.jpg
The URI of the “rivers” folder in the “Land” project is as follows:
files:///Land/rivers/
Note the trailing slash on the folder name. This is characteristic of URIs for all file containers.
There are root containers for other types of entities in a Version Cue project, which have a URI
such as collections:///.
URI for Other Model Objects
The URI for an instance of IVersion corresponds exactly to the URI of the file of which it is a
version. In other words, it has different semantics from the URI for a file or folder.
Other model objects associated with versions, such as instances of IThumbnail and IXMPMetadata, have no associated URI.
Namespaces
The identities of assets and versions have a namespace associated with them; see IAssetidentity
and IVersionIdentity. The default namespace for Version Cue Server objects is com.adobe.ver-
sioncue.
Allowing objects to be part of a namespace enables Version Cue Server to handle assets correctly within the normal Version Cue business logic, even when these assets are stored in
external systems. For instance, the controller layer determines the appropriate controller to
execute an operation, using the namespace information; see “Controller Layer” on page 11.
Third-party developers who want to allow Version Cue clients to browse an external system
need to distinguish their assets from Adobe assets. You supply a namespace when you implement an asset identity or a version identity, IAssetIdentity and IVersionIdentity respectively;
see “Asset and Version Identities” on page 33. You must use a different namespace than the
default namespace. For example, you might use something like “ns.com.yourco.yourproject.”
The key point is that it must be different than the Adobe default, “com.adobe.versioncue.”
There are constraints on namespace names: for instance, they cannot contain “_” (underscore)
characters.
32
Asset and Version Identities
Assets in the standard Version Cue Server model are represented by IAsset and subinterfaces;
for example, IProject for projects, IFile for files, and IFileContainer for folders. We call these
heavyweight business objects, and they are encapsulated in the model layer of the Version Cue
Server architecture. Instances of these interfaces represents assets in a standard Version Cue
project.
A major part of extensibility is concerned with external assets. These are not represented by
heavyweight business objects but can be represented by identity objects. They are instances of
IAssetIdentity and/ or IVersionIdentity. If an asset is an external asset, no heavyweight business object in the Version Cue Server represents it; its data is not stored directly on the Version
Cue Server, but its content and metadata are held in an external system.
Any identity objects exist within an associated namespace; see “Namespaces” on page 32.
There is a mechanism to turn identity objects into asset views. This is described in the extensibility section, under “Influencing how Assets Display at the Client via Asset-view Factory” on
page 57. The main point is that external assets are associated with identity objects in a different
namespace than the default “com.adobe.versioncue.”
Similarly, a version also can be associated with an identity object; in this case, an instance of
IVersionIdentity. This can be used to refer to a version in an external system, if the namespace
is different than the Adobe default. For instance, it might refer to a version of an asset in an
external revision control system that supports versioning.
Adobe Version Cue CS3 Server Programmer’s Guide
Sample Version Cue Server Model
To summarize, an identity object is a lightweight object that refers to an asset or version of
some kind, in two different ways:
1. It can be associated with an asset (or version) in a standard Version Cue project.
2. It can be associated with an external asset (or version); for instance, held in an external system. See Case Study: Connecting to an External System through Adobe Version Cue CS3.
Asset Views
A Version Cue client displays views of assets. These views can include thumbnails and other
metadata, such as XMP-based metadata or the time an asset was last modified, its name, and so
on. To construct these asset views, the client sends messages to the Version Cue Server, which
result in controller calls. Controller calls related to assets return lightweight identity objects
(IAssetIdentity or IVersionIdentity), rather than heavyweight business objects such as IAsset,
IProject, or IVersion.
Sample Version Cue Server Model
“Version Cue Server Model” on page 20 describes the model at a fairly abstract level. To make
it easier to understand the model, some concrete examples of the business objects for a project
containing different patterns of files, folders and versions are presented below.
Adobe Version Cue CS3 Server Programmer’s Guide 33
Adobe Version Cue CS3 Server Programmer’s Guide
Sample Version Cue Server Model
In the following diagrams (Figure 19 through Figure 23), we emphasize the structural relation-
ships between objects in the model. This is shown in a series of figures across the next few sections:
z Figure 19 shows the structure of a new project named Land; this might be created using
Adobe Bridge CS3 > Tools > Version Cue > New Project. The structure consists of a project
(IProject) named Land and a file root container (IFileRootContainer) named “files.” Other
types of root containers also exist within the empty project, but these are not shown, since
the focus of the example is to illustrate the model for file assets.
z Figure 20 shows an object diagram after an image file named hill.jpg is dragged and
dropped on the project. The structure now has a file (IFile) named “hill.jpg,” its first version (IVersion), and associated version-specific metadata (IXMPMetadata, IThumbnail).
z Figure 21 shows an object diagram after a check-out operation on hill.jpg. The structure
now has a lock (ILock) on the file.
z Figure 22 shows an object diagram after the edited file is checked into Version Cue. The
lock on the file has disappeared, but a second version appears, along with and associated
version-specific metadata.
z Figure 23 shows an object diagram after creating a folder named “rivers” within the project.
The structure now has a file container named “rivers.”
Later, Figure 43 is a class diagram showing the general associations between the business
objects involved in the above steps.
Empty Project
The object diagram in Figure 19 shows some of the objects representing an “empty” project.
The project root itself is represented by an instance of IProject. Even though the project does
not contain any files or folders visible in Version Cue clients such as Adobe Bridge CS3, the
project (IProject instance) has a child that is a file root container named “files,” present by
default in every Version Cue CS3 project. This structure holds for all Version Cue CS3
projects.
FIGURE 19 File Containers in an Empty Project
Land :IProject
IProject
files :IFileRootContainer
34
NOTE: In Version Cue CS2 projects, there was a file container (IFileContainer instance)
named “documents” that used to be a direct child of the “files” root container. This
“documents” folder is not present by default in projects created with Version Cue CS3,
unless you choose to create “CS2 compatible” projects, meaning they have this
“documents” file container.
One Version of a File
Adding a file to the project creates a file and its first version; see the object diagram in
Figure 20. The version has metadata associated with it: thumbnails in different sizes and XMP
metadata.
FIGURE 20 One Version of a File in a Project
Adobe Version Cue CS3 Server Programmer’s Guide
Sample Version Cue Server Model
Land :IProject
:IXMPMetadata
hill.jpg :
IVersion
small :
IThumbnail
IProject
files :IFileRootContainer
IAssetContainer
hill.jpg :IFile
IVersionableAsset
preview :
IThumbnail
Adobe Version Cue CS3 Server Programmer’s Guide 35
Adobe Version Cue CS3 Server Programmer’s Guide
Sample Version Cue Server Model
File Being Edited
Checking out the file for edit results in a lock (ILock) being created, associated with the file.
See Figure 21.
FIGURE 21 Locked File
Land :IProject
IProject
files :IFileRootContainer
IAssetContainer
:IXMPMetadata
hill.jpg :
IVersion
small :
IThumbnail
IVersionableAsset
preview :
IThumbnail
hill.jpg :IFile
IAsset
lock :ILock
36
Two Versions of a File
The file is checked back in, to create a new version. See Figure 22. The lock disappears, but a
new version is created, which is shown along with the metadata objects.
FIGURE 22 Two Versions of a File in a Project
Adobe Version Cue CS3 Server Programmer’s Guide
Sample Version Cue Server Model
Land :IProject
IProject
files :IFileRootContainer
IAssetContainer
hill.jpg :IFile
IVersionableAsset
hill.jpg :
IVersion
:IXMPMetadata preview :
small :
IThumbnail
preview :
IThumbnail
:IXMPMetadata
hill.jpg :
IVersion
small :
IThumbnail
IThumbnail
Adobe Version Cue CS3 Server Programmer’s Guide 37
Adobe Version Cue CS3 Server Programmer’s Guide
Version Cue and the Development Platform
Two Versions of a File Plus a Folder
A folder named “rivers” is added to the project, appearing as a new file container. See
Figure 23.
FIGURE 23 Two Versions of a File plus a Folder in a Project
Land :IProject
IProject
files :IFileRootContainer
IAssetContainer
hill.jpg :
IVersion
small :
IThumbnail
:IXMPMetadata
hill.jpg :
IVersion
small :
IThumbnail
IVersionableAsset
preview :
IThumbnail
IAssetContainer
hill.jpg :IFile
:IXMPMetadata
Version Cue and the Development Platform
rivers :
IFileContainer
preview :
IThumbnail
38
Version Cue Server is an Eclipse-based product, which uses the Eclipse run-time and plug-in
architecture. Version Cue SDK also is an Eclipse-based product, which extends the Eclipse
IDE with plug-ins developed by Adobe.
This section introduces the Eclipse platform and its major components, and it discusses the
relationship between Version Cue SDK and the “standard” Eclipse IDE. Visit
http://www.eclipse.org for more information about Eclipse and the Eclipse Consortium, the
developers of Eclipse.
Adobe Version Cue CS3 Server Programmer’s Guide
Version Cue and the Development Platform
Eclipse, Version Cue Server, and Version Cue SDK
Eclipse is an IDE for writing programs in Java (and other languages). It also is a run-time environment for applications, with a relatively sophisticated plug-in architecture. Version Cue
Server is based on Eclipse; it uses the run-time environment and plug-in architecture of
Eclipse. The run-time environment starts the platform base, and it dynamically discovers and
loads on demand the plug-ins comprising Version Cue Server.
Figure 24 makes explicit the dependence of Version Cue Server on the Eclipse platform base.
Version Cue Server is implemented as a set of plug-ins for Eclipse. The core run-time environment discovers and starts on demand the plug-ins that implement the features of Version Cue
Server.
FIGURE 24 Version Cue Server and Eclipse
Version Cue Server
Eclipse platform base
Core runtime
OSGI framework
A plug-in for Version Cue Server is a structured component that describes itself to the Version
Cue Server run-time environment via its manifest; see “Plug-ins” on page 40. The Eclipse plug-
in model is efficient, in the sense that plug-ins are not loaded unnecessarily. The plug-in manifest is loaded by the run-time environment, to let Version Cue Server find out the plug-in’s
capabilities. The plug-in itself is loaded on demand (or lazily) by Version Cue Server.
The Version Cue SDK is a customized version of the Eclipse IDE, with Adobe-specific plug-ins
to contribute functionality, documentation, and sample code to the core Eclipse IDE. We
strongly recommend the Version Cue SDK for developing and debugging Version Cue Server
plug-ins.
For example, inside the Version Cue SDK, there is a plug-in called com.adobe.versioncue.sdk.samples_..., within which is compressed sample code for the Version Cue SDK sample
Adobe Version Cue CS3 Server Programmer’s Guide 39
Adobe Version Cue CS3 Server Programmer’s Guide
Version Cue and the Development Platform
plug-ins. This plug-in contributes a wizard that lets you import samples directly from the Welcome screen of Version Cue SDK.
The target platform for your plug-in development with Version Cue SDK is “Version Cue
Server.” This target platform consists of the minimal run-time core needed to load and manage plug-ins, plus the set of plug-ins implementing Version Cue Server. See Getting Started
with Adobe Version Cue CS3 Development (getting-started.pdf) for more instructions on starting to develop plug-ins for Version Cue Server.
Help on Eclipse itself when using the Version Cue SDK can be found using the menu item
Help > Help Contents. Look in the Help under Platform plug-in Developer Guide > Programmers Guide > Run-time Overview for further documentation on developing for the Eclipse
run-time environment.
Features
Eclipse-based products are structured as collections of plug-ins that operate together to provide
a common function; these are called features. Features are used to structure Eclipse-based
products, to give them a well defined, modular organization.
Plug-ins
Version Cue Server is broken down into several features. Some of these features correspond to
layers in the basic architecture, described in “Version Cue Architecture” on page 6; for
instance, there is a controller feature and a (protocol) manager feature. There also are features
spanning several layers of the architecture; for instance, the PDF Review feature. You can see
the set of features that compose Version Cue Server in the “features” folder within the application folder.
A plug-in is the fundamental unit for packaging functionality in any Eclipse-based product.
The plug-in is a structured bundle of code and/or data that contributes function to the target
platform.
Version Cue Server is an Eclipse-based product, and you develop plug-ins for it using the Version Cue SDK IDE, another Eclipse-based product. Any plug-in for Version Cue Server must
be an Eclipse-based plug-in. Version Cue Server is described as the target platform for plug-in
development when using the Version Cue SDK IDE. A target platform is just a collection of
Eclipse plug-ins that will host your own plug-in.
Plug-ins for Version Cue Server should subclass com.adobe.versioncue.core.VCPlugin, which
also lets you use services such as Version Cue Server logging and accessing the global Version
Cue Server preferences.
To register on existing extension points of Version Cue Server, you must implement extensions. You declare extensions in your plug-in manifest, to let you register with the extension
points of Version Cue Server; see “Extension Points and Extensions” on page 41. You then
typically provide implementations of the interfaces required by these extensions by writing
Java code, most often extending adapter classes in the Version Cue Server API providing partial implementations of these interfaces. See Getting Started with Adobe Version Cue CS3
40
Development (getting-started.pdf) for details on how to write your first plug-in for Version
Cue Server.
Within Help in your Version Cue SDK IDE, navigate to the named Platform plug-in Developer Guide, and visit the section Runtime overview > The plug-in runtime model. In the Platform plug-in Developer Guide, see the section Packaging and delivering Eclipse based
products > Plug-ins and fragments.
Within Help in your Version Cue SDK IDE, navigate to the section named Platform plug-in
Developer Guide > Reference > Other Reference Information, and see the sections named
Plug-in Manifest and OSGi Bundle Manifest.
Extension Points and Extensions
Plug-ins can define Eclipse-based extension points; these are well defined function points that
can be extended by other plug-ins. An extension point is defined using an XML-based schema.
Version Cue extensibility is based on the extension points exposed by components in the Version Cue Server architecture.
Your plug-ins implement extensions, which register with the extension points provided by the
target platform, Version Cue Server. Implementing an extension lets your code be called by the
Eclipse-based product you are extending.
Adobe Version Cue CS3 Server Programmer’s Guide
Version Cue and the Development Platform
For example, the controller layer exposes extension points that notify listeners about events
happening in that layer. You can be notified of events like an asset being deleted or stored on
the Version Cue Server, by registering on the extension point named controller listener (as
described in “Notification about Controller Events and the Controller Listener” on page 42)
and implementing the appropriate interface. Then your plug-in code is called when an asset is
deleted or stored on the Server.
Implementing extensions is the main way to integrate with Version Cue Server. Once you
know its extension points, you implement extensions to connect with them. To implement an
extension, you typically edit the plug-in manifest and implement an interface. A detailed
description of the extension points provided by Version Cue Server is in the Extension Points
Reference; also see “Version Cue Server Extensibility” on page 42.
When starting to develop for Version Cue Server, the existing extension points provided by
Version Cue Server are likely to be of most interest, rather than defining your own extension
points. Subsequently, you may decide to define your own extension points. The Version Cue
SDK sample named SnippetRunner is an example. It defines a codesnippet extension point, to
let arbitrary plug-ins define codesnippet extensions, which can be run from the SnippetRunner
user interface.
Adobe Version Cue CS3 Server Programmer’s Guide 41
Adobe Version Cue CS3 Server Programmer’s Guide
Version Cue Server Extensibility
Version Cue Server Extensibility
Overview of Integrating with Version Cue Server
This section is a conceptual description of use cases connected with integrating with and
extending Version Cue, and it describes some of the extension points of Version Cue Server.
For a more detailed description of individual extension points, see the Extension Point Refer-
ence.
Plug-ins for Version Cue Server are developed using the Version Cue SDK. Your plug-ins
should implement one or more extensions, which let you register on the published extension
points of Version Cue Server and be called by Version Cue Server at appropriate times. For
example:
z The protocol manager layer provides extension points that allow administration of a plug-
in via a Web page. See “Supporting Dynamic Pages with a Web Application” on page 52
and “Adding to the Administration Interface and Plug-in Admin” on page 60.
z The controller layer provides extension points that allow plug-ins to override (replace)
and/or extend (decorate) the Version Cue business logic for an operation. If an operation is
overridden, the Version Cue business logic for the operation does not execute; see “Inter-
cepting Controller Events with a Valve” on page45. If an operation is extended, the Ver-
sion Cue business logic for the operation executes; see “Notification about Controller
Events and the Controller Listener” on page 42.
z The controller layer exposes an extension point to enable controller calls to operate with
external assets. See “Customizing Controller Logic to Connect to External Systems” on
page 54.
z The model layer provides the business objects in the Version Cue Server model. See “Ver-
sion Cue Server Model” on page 20. These should be updated only from within the scope of
a running transaction; for example, from the scope of a controller listener that is being
notified on an update of the business objects, not a read-only call. See the Extension Point
Reference for an indication of whether listeners are notified in the scope of a read-only or
update call.
z The persistence layer is responsible for managing transactions. The persistence layer noti-
fies listeners of low-level transaction-related events. See “Transaction-related Events and
the Unit-of-Work Listener” on page 49.
Do not update the underlying database directly.
Notification about Controller Events and the Controller Listener
Plug-ins can extend the Version Cue business logic for an operation using a controller listener.
Figure 25 shows the controller listener extension point exposed by the controller layer and a
plug-in that provides a listener extension connecting with the extension point. A controller listener is notified on controller events for which it has registered.
42
Adobe Version Cue CS3 Server Programmer’s Guide
FIGURE 25 Plug-in with Controller Listener
Version Cue Server
Protocol manager
Version Cue Server Extensibility
Controller
Model
Persistence
controller listener
Plug-in
When a controller executes an operation, it raises a controller event. For example, when a new
project is created, the project create controller event occurs. Controller events are listed in the
Extension Points Reference.
To be notified about controller events, register on the controller listener extension point,
com.adobe.versioncue.controller.core.listener. To implement a controller listener, use the
Version Cue SDK to add an extension to your plug-in manifest and implement the required
Adobe Version Cue CS3 Server Programmer’s Guide 43
Adobe Version Cue CS3 Server Programmer’s Guide
Version Cue Server Extensibility
interface indicated in the Extension Point Reference; the process is described in detail in Getting
Started with Adobe Version Cue CS3 Development (getting-started.pdf).
For each interface associated with a controller listener, a method is called before (preCall) and
after (postCall) the controller operation executes. Detailed documentation on the semantics of
these methods is in the API Reference.
Your controller listener’s preCall method is called at the start of the operation, before the Version Cue business logic is executed. Briefly, the preCall method can do the following:
z Perform pre-processing.
z Throw an exception to abort the operation, and return an error to the Version Cue client.
Your controller listener’s postCall method is called at the end of the operation, after the Version Cue business logic for the operation is executed or suppressed. Briefly, the postCall
method can do the following:
z Perform post processing.
z Throw an exception to abort the operation, and return an error to the Version Cue client.
For example, assume you want to perform an action whenever a new project is created in the
Version Cue Server. If you implement a controller listener for the project create event in your
plug-in, your plug-in is notified before and after the project is created. Figure 26 shows the
pattern of messages exchanged between the Version Cue Server project controller and a listener extension. The listener, CreateListener, is called before and after the project controller
executes the operation to create a project.
FIGURE 26 Controller-Listener Interaction
CreateListenerProjectController
preCall
postCall
From this extension, you can customize the behavior of Version Cue Server. For example, you
can take custom action before and/or after the create project operation is executed. To take
advantage of this extension point, add a controller listener extension to your plug-in’s manifest
in Version Cue SDK for the create project event, and implement the required interface, ICreateListener. The operation to create a project then acts as a trigger for your own action.
The DropFolder sample uses this listener to create a folder when a project is created on the
Version Cue Server. See the Samples Guide for its documentation.
44
Adobe Version Cue CS3 Server Programmer’s Guide
NOTE: Listeners can be stateful; in other words, your implementation of the listener interface
can have instance variables. This is not true of some other extensions; for example, see
“Intercepting Controller Events with a Valve” on page 45.
NOTE: If you implement a custom controller, as described in “Customizing Controller Logic
to Connect to External Systems” on page 54, listeners are not notified on controller
events affecting only external assets. The notification mechanism for controller
listeners is part of the Version Cue Server controller implementation.
See the Extension Point Reference for a more detailed description of the controller-listener
extension point.
Intercepting Controller Events with a Valve
Plug-ins can both extend (decorate) and override (replace) the Version Cue business logic for
an operation using a controller valve; see Figure 27. The controller valve mechanism is a vari-
ant of the “Chain of Responsibility” pattern, described as follows:
“Avoid coupling the sender of a request to its receiver by giving more than one object a chance to
handle the request. Chain the receiving objects and pass the request along the chain until an
object handles it.” (Gamma et al, 1995)
Version Cue Server Extensibility
Adobe Version Cue CS3 Server Programmer’s Guide 45
Adobe Version Cue CS3 Server Programmer’s Guide
Version Cue Server Extensibility
FIGURE 27 Plug-in with Controller Valve
Version Cue Server
Protocol manager
Controller
Controller valve
Plug-in
Model
Persistence
Figure 27 shows a plug-in with a controller valve extension; the corresponding extension point
is exposed by the controller layer. Controller valves are called before the Version Cue business
logic for an operation is executed; for instance, before the project controller creates a new
project. If any controller valve chooses not to invokeNext to pass control to the next valve, the
Version Cue business logic for the operation is not executed. A typical controller valve
sequence is illustrated in Figure 28.
46
Adobe Version Cue CS3 Server Programmer’s Guide
FIGURE 28 Controller-valve Sequence Diagram
Version Cue Server Extensibility
Client Controller ValveContext ControllerValve1 VersionCue-
request
firePreEvents
new()
executeItem
invokeNext
executeItem
invokeNext
ControllerValve2
ControllerValve
executeItem
response
response
firePostEvents
response
In this sequence, each valve has called
invokeNext on the context, to pass on
flow. The Version Cue Server valve, last in
the chain, has no successor, and here is
shown returning control
above, via the context.
to the valve
Figure 28 shows the message sequence with two controller valve extensions provided by third-
party plug-ins, ControllerValve1 and ControllerValve2. If these valves do not handle the operation, as shown in the figure, the VersionCueControllerValve is called to execute the Version
Cue business logic. Only one valve in the chain can override the operation. The object
returned by the valve that overrides the operation is returned to the Version Cue client by the
controller layer. Note in Figure 28 we collapsed the Version Cue client and protocol manager
layers and denoted this by “Client.”
Adobe Version Cue CS3 Server Programmer’s Guide 47
Adobe Version Cue CS3 Server Programmer’s Guide
Version Cue Server Extensibility
There are two variants of controller valves: valves that are generic (<valve>) and valves that
override a specific operation (<functionvalve>). To override only one operation, use a <functionvalve>; see DropFolder sample for an example.
The controller valve extension point is identified in Ta bl e 1 . To implement a controller valve,
add an extension to your plug-in’s manifest in Version Cue SDK, and provide an implementation of the required interface, IValve. See the Extension Point Reference and API Reference for
details.
TABLE 1 Controller Valve Extension Point
Extension Point Required Interface
com.adobe.versioncue.controller.core.valve IValve
When the executeItem method in an IValve implementation is called, your code can determine whether to override the operation being performed. It then has several choices:
1. The valve can perform some pre-processing before the operation takes place.
2. If the valve will not override the operation, it must pass responsibility to the next valve in
the chain:
return valveContext.invokeNext(parameter);
3. If the valve will override the operation, it can do so. (Note overrideOperation() shown
below is some notional operation offered by the implementation of the IValve interface.)
Object result = this.overrideOperation();
return result;
4. If the valve is required to post-process the result of an override by other valves in the chain,
it can do so as follows:
Object result = valveContext.invokeNext(parameter);
// Post-process the result here...
return result;
For example, suppose you want to implement a watched folder in a Version Cue project that
exports assets moved to that folder to an external location. You want the asset that was moved
to the watched folder to be left in its original location. You can override the Version Cue business logic for a move asset operation. The DropFolder sample uses a controller valve to implement this use case; see the Samples Guide.
48
Adobe Version Cue CS3 Server Programmer’s Guide
Version Cue Server Extensibility
NOTE: Valves must be stateless, as they are cached for performance reasons. In other words,
you cannot have instance variables in your implementation of IValve, as these will lose
their values when Version Cue Server removes your extension from primary memory
on caching. There also are concurrency issues; all controller calls can be executed in
parallel, and a single instance of your valve would be used for all these calls, so your
valve implementation should not try to maintain state.
NOTE: You should be aware of the performance implications if you implement a generic valve.
Your code is called on every controller operation, and your code should return as
quickly as possible when a particular controller call is not of interest. The functionvalve
is preferable, as you are called only on the operation of interest.
For more detail about the controller-valve extension point, see the Extension Point Reference.
Transaction-related Events and the Unit-of-Work Listener
Plug-ins can be called before and after a transaction is committed or rolled back, using a unit
of work listener; see Figure 29. A plug-in must implement the IUnitOfWorkListener interface.
There is no extension point corresponding to a unit-of-work listener, and the unit-of-work listener must be registered dynamically. For instance, you can register a unit-of-work listener
using a controller listener, as long as the controller listener is for an update call; see “Notifica-
tion about Controller Events and the Controller Listener” on page 42 and the Extension Point
Reference for details. Read-only calls do not have an associated unit-of-work listener.
Adobe Version Cue CS3 Server Programmer’s Guide 49
Adobe Version Cue CS3 Server Programmer’s Guide
Version Cue Server Extensibility
FIGURE 29 Plug-in with Unit-of-Work Listener
Version Cue Server
Protocol manager
Controller
Model
Persistence
IUnitOfWorkListener
Plug-in (UoW
Listener)
Figure 29 shows a plug-in that implements an IUnitOfWorkListener interface, which connects
it with the Persistence layer. Each transaction that updates the database has a unit of work
associated with it; see interface IUnitOfWork. To observe the transaction, create and register a
unit of work listener with code like the following:
IUnitOfWork unitOfWork = UnitOfWork.currentUnitOfWork();
IUnitOfWorkListener uowListener = new YourUnitOfWorkListener();
unitOfWork.registerListener(uowListener);
50
Adobe Version Cue CS3 Server Programmer’s Guide
Version Cue Server Extensibility
Figure 30 shows the sequence of messages sent to a unit-of-work listener when a transaction is
committed. Only the preCommitTransaction is still in the scope of the transaction; by the time
you get the postCommitTransaction message, the transaction is over and committed. This
means you could manipulate the model directly only on preCommitTransaction. A unit-ofwork listener is notified when a transaction succeeds (before and after commit) or fails (before
and after rollback); see Figure 30 and Figure 31.
FIGURE 30 Controller and Unit-of-Work Listener Interaction on Commit
UnitOfWorkListenerPersistence layer
preCommitTransaction
postCommitTransaction
cleanUp
Figure 31 shows the sequence of messages sent to a unit of work listener only when a transac-
tion is rolled back. In the event of a transaction being rolled back and not committed, these are
the only messages sent to the unit of work listener.
FIGURE 31 Controller and Unit-of-Work Listener Interaction on Rollback
UnitOfWorkListenerPersistence layer
preRollbackTransaction
postRollbackTransaction
cleanUp
Adobe Version Cue CS3 Server Programmer’s Guide 51
Adobe Version Cue CS3 Server Programmer’s Guide
Version Cue Server Extensibility
NOTE: You cannot invoke controller operations from the scope of a unit-of-work listener. The
unit-of-work listener is not associated with an extension point of Version Cue Server,
so you do not have corresponding entries in your plug-in manifest, and the listener is
not listed in the Extension Point Reference. For more detail about the unit-of-work
listener, see the API documentation for IUnitOfWorkListener.
Notification Sequence for Valves and Listeners
The controller layer calls the valves at the listeners at determined points during the execution
of a controller call. The general pattern of calls is shown in Figure 32, for the specific case of
creating a new project.
FIGURE 32 Order in which Extensions are Called by Controller
Controller CreateProjectListener UnitOfWorkListenerController-
CallValve1
preCall
executeItem
postCall
Pers istence layer
preCommitTransaction
postCommitTransaction
cleanUp
Figure 32 shows the order in which the different types of extension are called by the controller:
first the controller listener, then the controller valve, and once the success or failure of the
operation is known, the unit-of-work listener on the commit (in this case) or rollback. All
messages up to and including preCommitTransaction are in transaction scope, so you can
directly manipulate the model if you implement the corresponding methods.
52
Supporting Dynamic Pages with a Web Application
Figure 33 shows a plug-in with a Web application extension, which connects with the corre-
sponding extension point exposed by the protocol manager layer. To implement a Web application, add an extension to your plug-in’s manifest in Version Cue SDK, and provide an
implementation of the required interface, indicated in Ta bl e 2 . The plug-in also can provide
Adobe Version Cue CS3 Server Programmer’s Guide
Version Cue Server Extensibility
Java Server Pages (JSP) to support dynamic HTML page generation. See the Extension Point
Reference and API Reference.
FIGURE 33 Plug-in with Web Application Extension
Version Cue Server
Protocol manager
webApplication
Controller
Plug-in
Model
Persistence
Adobe Version Cue CS3 Server Programmer’s Guide 53
Adobe Version Cue CS3 Server Programmer’s Guide
Version Cue Server Extensibility
TABLE 2 Web Application Extension Point
Extension Point Required Interface
com.adobe.versioncue.tomcat.webApplication IWebApplication
The AuditTrail sample uses a Web application to create a log of operations performed on
assets on the Version Cue Server. See the Samples Guide.
To contribute Web pages to the Administration interface of Version Cue Server, you can use a
plug-in admin extension. See “Adding to the Administration Interface and Plug-in Admin” on
page 60.
See the Extension Point Reference for more detail about the Web application extension point.
Customizing Controller Logic to Connect to External Systems
If you implement a custom controller, you can execute controller calls involving external
assets. See Case Study: Connecting to an External System through Adobe Version Cue CS3.
The controller layer exposes an extension point named:
com.adobe.versioncue.controller.core.controller
If you register on this extension point and implement an IController subinterfaces, we call this
as a custom controller implementation. Note that if you implement a custom controller, such as
a custom project controller, then it is associated with a particular namespace; you must also
implement an asset-view factory for that namespace, as described in “Influencing how Assets
Display at the Client via Asset-view Factory” on page 57.
Version Cue Server already provides implementations of IController subinterfaces, such as
IProjectController, IMetadataController, IAssetController, and ISearchController. We refer to
these as Version Cue Server controllers. If you provide a custom controller implementation,
you can override the behavior of the corresponding Version Cue Server controller.
A key use case for custom controller implementations is connecting to an external system.
This requires a design pattern with multiple controller implementations, which is described in
Case Study: Connecting to an External System through Adobe Version Cue CS3.
The controller is an extension point of the controller layer, as shown in Figure 34. If you
implement a custom controller, your code can execute in response to some controller calls,
completely bypassing the normal Version Cue Server business logic.
54
Adobe Version Cue CS3 Server Programmer’s Guide
FIGURE 34 Plug-in with Custom Controller Extension
Version Cue Server
Protocol manager
Version Cue Server Extensibility
Controller
Model
Persistence
custom controller
Plug-in
Ta bl e 3 shows controllers that can be implemented and adapter classes provided in the API to
be used in implementation. Some of the methods on these adapter classes are marked as
abstract, indicating a minimum level of capability should be provided.
TABLE 3 Custom controllers
IController Subinterface Adapter Class Minimum Responsibility
IProjectController ProjectControllerAdapter Allows browsing of projects
IAssetController AssetControllerAdapter Allow browsing of assets
Adobe Version Cue CS3 Server Programmer’s Guide 55
Adobe Version Cue CS3 Server Programmer’s Guide
Version Cue Server Extensibility
IController Subinterface Adapter Class Minimum Responsibility
IMetadataController MetadataControllerAdapter Provide thumbnail for given version
ISearchController SearchControllerAdapter Allows searching of assets
This minimum level of capability is geared toward the use cases of browsing an external system
and searching its assets. See Case Study: Connecting to an External System through Adobe Ver-
sion Cue CS3.
There are two different ways in which custom controllers can be called:
z In a unicast mode, when the controller call returns a result that is not an array. For exam-
ple, IAssetController.createFileContainer(...) returns an IFileContainer instance rather
than a collection, since the request is to create a single container rather than multiple containers. The results of unicast controller calls are not merged.
z In a broadcast mode, when the controller call returns an array result and the results from
different controllers can be logically merged. For example, the message named IProjectController.findByUser(...) is broadcast to all project controllers.
See the Extension Point Reference for more detail about the controller-valve extension point,
and see Case Study: Connecting to an External System through Adobe Version Cue CS3 for
more information on using custom controllers.
Customizing Icons for Assets
You can control the appearance of assets in a standard Version Cue project, such as giving a
folder with special status in your workflow a customized appearance. If you register on the
asset icon provider extension point, you can take control when icons for a particular asset—
identified by model object identifier— are being requested.
An example of this might be where you want to make a visually distinctive folder, such as hot
folder or action folder in a standard Version Cue project; when an asset is dropped in the action
folder, some custom logic of your own executes.
Ta bl e 4 shows the fully qualified name of the extension point and the interface it must imple-
ment.
TABLE 4 Asset Icon Provider Extension Point
Extension Point Required Interface
com.adobe.versioncue.model.assetIconProvider IAssetIconProvider
Your implementation of IAssetIconProvider is called once initially to determine what assets
you can provide icons for, and then you are called repeatedly for the assets that you claim to
provide icons for. You must know the model-object identifiers in the Version Cue model for
any assets that you want to provide icons for— so this extension point does not apply to exter-
nal assets in some external project.
56
Adobe Version Cue CS3 Server Programmer’s Guide
Version Cue Server Extensibility
NOTE: Because your implementation can be called many times by the Version Cue Server core
to request a particular icon, you must make your implementation of
IAssetIconProvider as efficient as you possibly can, otherwise it can represent a real
performance bottleneck.
Use of this extension point is illustrated in the sample named sample.dropfolder, which implements an action folder to export files/folders dropped in a particular visually distinctive folder
in a standard Version Cue project to a location in the server file system. You will find that the
sample.dropfolder code registers on the assetIconProvider extension point to provide a customized appearance for its action folder.
Influencing how Assets Display at the Client via Asset-view Factory
A plug-in can influence how assets are displayed in the Version Cue client, if the plug-in provides an implementation of an asset-view factory extension for a particular namespace.
If you implement an asset-view factory extension, you can be called just before the protocol
manager creates SOAP response messages associated with that namespace, with the results of
controller operations for that specific namespace.
NOTE: Implementing an asset-view factory is a mandatory part of implementing custom
controllers to connect to an external system, as described in Case Study: Connecting to
an External System through Adobe Version Cue CS3]. Note also you cannot under any
circumstances override the asset-view factory for the default Adobe namespace
com.adobe.versioncue; further, you should have only a single asset-view factory per
namespace of your own.
The asset-view factory is an extension point of the protocol manager layer, shown in Figure 35.
If you register on this extension point, you can be called to resolve identity objects—within a
specific namespace—to stateful objects that store information needed by the Version Cue client to display a view of assets. See “Namespaces” on page 32.
Adobe Version Cue CS3 Server Programmer’s Guide 57
Adobe Version Cue CS3 Server Programmer’s Guide
Version Cue Server Extensibility
FIGURE 35 Plug-in with Custom Asset-View Factory
Version Cue Server
Protocol manager
asset view factory
Controller
Plug-in
Model
Persistence
The asset-view factory is associated with an assetViewFactory extension point, with the follow-
ing fully qualified name:
com.adobe.versioncue.model.assetViewFactory
If you register on this extension point and implement the appropriate interface, you can be
called when identity objects are resolved into asset views, containing information needed for
the Version Cue client. The reason this extension point is so closely associated with the Browse
functionality is that the asset-view factory is associated with a namespace; see Example1. The
definition of the extension asserts that a particular asset-view factory should be used for resolving identity objects in a specific namespace.
58
Adobe Version Cue CS3 Server Programmer’s Guide
Version Cue Server Extensibility
EXAMPLE 1
<extension
point="com.adobe.versioncue.model.assetViewFactory">
<factory
namespace="ns.sample.customproject"
class="sample.customproject.AssetViewFactory"/>
</extension>
OTE: Do not try to override the default asset-view factory implementation for the Adobe
N
namespace com.adobe.versioncue. An asset-view factory should be used only in
conjunction with implementations of controller extensions; see “Customizing
Controller Logic to Connect to External Systems” on page 54. Implementing an asset-
view factory is an essential part of connecting to an external system; see Case Study:
Connecting to an External System through Adobe Version Cue CS3.
Figure 36 is a conceptual view of the Version Cue Server responding to a request to explore
assets; for example, to get the files and folders within a particular folder. When a SOAP message is received, the protocol manager calls into the controller layer to perform operations, like
exploring assets in the Version Cue Server. Controller calls can result in one or more objects
being returned to the protocol manager. Once the controller call is executed, the results need
to be serialized into a SOAP response message by the protocol manager layer.
FIGURE 36 Interaction between Asset-View Factory and Other Entities
Version Cue
Client
SOAP request
SOAP response
Protocol
manager
factory
explore
identity objects
create
asset view map
Asset controllerAsset view
Adobe Version Cue CS3 Server Programmer’s Guide 59
Adobe Version Cue CS3 Server Programmer’s Guide
Version Cue Server Extensibility
Rather than returning heavyweight model objects, such as IAsset instances, with a great deal of
stateful information, the controller calls return lightweight identity objects with very little state
(for example, IAssetIdentity instances), See IProjectController.findByUser(...) and “As s et and
Version Identities” on page 33.
Having controller calls returning identity objects rather than model objects directly is a key
part of the extensibility strategy. This lets you take control before the controller results are sent
back to the client and turns a token representation of an asset into a detailed view for the Version Cue client.
The Version Cue client displays views of assets; see “Asset Views” on page33. These assets
exist either in the Version Cue Server model, in which case they are internal assets, or outside
the Version Cue Server model, in which case they are external assets. To construct the views,
the client sends messages to the Version Cue Server, which results in controller calls.
Version Cue Server uses the asset-view factory mechanism to turn lightweight identity objects
into asset views for a Version Cue client. For instance, a call to explore assets returns an array
of identity objects, which have no state that is directly meaningful to the client. These identity
objects need are resolved into asset views.
The asset-view factory is responsible for translating identity objects into stateful objects, which
can be serialized into a SOAP response message. These effectively provide a read-only view of
a subset of the model data. In the case of external assets, you control what information you
provide to create this asset view.
See the Extension Point Reference for more detail about the asset-view factory extension point.
Adding to the Administration Interface and Plug-in Admin
If you implement a plug-in for Version Cue Server, you want Version Cue Server administrators to be aware of the presence of your plug-in and, perhaps, be able to configure it. The pluginAdmin extension point is used when you want your plug-in name and details to appear on a
section within the Administration user interface for the Version Cue Server. This extension
point also gives you the option to create a preference page.
You can bring up the Administration pages from Adobe Bridge when a Version Cue Server is
selected in the content area, using the context-sensitive menu and the item Edit Properties >
Advanced Information.
Figure 37 shows the pluginAdmin extension point, exposed by the protocol manager layer.
60
Adobe Version Cue CS3 Server Programmer’s Guide
FIGURE 37 Plug-in with a pluginAdmin Extension
Version Cue Server
Protocol manager
pluginAdmin
Controller
Version Cue Server Extensibility
Plug-in
Model
Persistence
The pluginAdmin extension point has the following fully qualified name:
com.adobe.versioncue.ui.admin.api.pluginAdmin
If you register on the pluginAdmin extension point, you can have the name of your plug-in
and a custom icon appear on the Plug-ins Overview page, as shown in Figure 38.
Adobe Version Cue CS3 Server Programmer’s Guide 61
Adobe Version Cue CS3 Server Programmer’s Guide
Version Cue Server Extensibility
FIGURE 38 Plug-ins Overview Page
If you go further and provide an implementation of the IPluginAdminActions interface and
other collateral for a Web application (for example, a JSP page), you can have a preferences
(settings) page for your plug-in, which appears when the Administration option is chosen. See
Figure 39.
FIGURE 39 Preferences Page for a Version Cue SDK Plug-in
62
Figure 40 shows the sequence of events that take place when an end user visits the Plug-ins
Overview page within the Administration user interface (Figure 38), if you provided an implementation of IPluginAdminActions. You are sent messages before and after the user navigates
to your custom preferences page. You would expect to load (restore) your settings before the
page displays and save the settings after the end user changes them.
Adobe Version Cue CS3 Server Programmer’s Guide
FIGURE 40 pluginAdmin Extension
Version Cue Server Extensibility
Web browser client
HTTP request
HTTP response
HTTP request
HTTP response
Server
Plugin-
AdminActions
loadPluginSettings
End-user has navigated to the settings
page and it is about to be displayed
savePluginSettings
End-user has applied the settings and
dismissed the settings page
See the Extension Point Reference for more detail about the plug-in admin extension point.
Contributing Client Resources
Suppose you want to create a custom user interface at the Version Cue client; for example, so a
non-Adobe dialog (under your control) appears and an end user is required to fill out metadata fields before an asset can be checked in to a standard Version Cue project. For instance,
you may do this to customize the Version Cue check-in dialog in Version Cue clients like
Adobe InDesign CS3 or Adobe Photoshop® CS3. Alternately, you may want to contribute
menu elements to a context-sensitive menu item on the Version Cue client and then run custom logic at the client end on executing the custom menu item.
Adobe Version Cue CS3 Server Programmer’s Guide 63
Adobe Version Cue CS3 Server Programmer’s Guide
Version Cue Server Extensibility
To do this for a standard Version Cue project, you must register on the following extension
point:
com.adobe.versioncue.controller.project.api.resourceProvider
Your Version Cue Server plug-in is called to send JavaScript and other resources to a Version
Cue client, to provide new user interface elements and/or logic to execute at the client.
NOTE: To customize resources for an external project, override
IProjectController.getResources(...) and return the appropriate resources from your
implementation of this. Extensions registered on the resourceProvider extension point
are called only for standard Version Cue projects.
The sequence diagram in Figure 41 shows the interaction between Version Cue client components and the Version Cue Server, and a Version Cue Server plug-in implementing a resource
provider. In this diagram, the resource provider is configured to return a script that is executed
on a check-in event. The initial call to the resource provider occurs when a project is being
opened for the first time at the Version Cue client; thereafter, the client may cache the script,
although you should not count on this behavior.
64
Adobe Version Cue CS3 Server Programmer’s Guide
FIGURE 41 Resource-Provider on Check-in Operation
Version Cue Client
Version Cue Server Extensibility
Creative Pro
check-in
(save version)
Adobe Common UI/
Bridge UI
Client Core Script Engine Server Server plug-in
getResources
getResource
IResource[]
Assume the Version Cue Server plug-in
has implemented a storeCon tent
listener. When called, the storeContent
listener gets access to a custom
parameter, containing data passed from
the client, say gathered through a
show dialog
storeContent
dialog.
preCall
Figure 41 also assumes that the Version Cue Server plug-in implements a store-content lis-
tener (listener for uploads of content to the Version Cue Server).
Ta bl e 5 shows the fully qualified name of the extension point and the interface it must imple-
ment.
TABLE 5 Resource-Provider Extension Point
Extension Point Required Interface
com.adobe.versioncue.controller.project.api.resourceProvider IResourceProvider
Adobe Version Cue CS3 Server Programmer’s Guide 65
Adobe Version Cue CS3 Server Programmer’s Guide
Version Cue Server Extensibility
Both the CustomDialog and CustomMenu samples use the resource provider extension point
to contribute user interface elements and logic to standard Version Cue projects; for instance,
in the case of Custom Dialog, to modify the check-in dialog when adding/ checking-in assets
to standard Version Cue projects. See the Samples Guide for documentation on these sample
plug-ins.
See the Extension Point Reference for more detail about the resource provider extension point.
Also see Client Programmer’s Guide for a guide to getting started with scripting at the Version
Cue client and in Adobe Bridge.
NOTE: To decorate an external project with additional resources, you can return resources
from your implementation of IProjectController.getResources(...). See
sample.customproject for an example of an implementation of this.
Customizing the Capabilities (Function) of a Project
Suppose you want to modify the capabilities exposed by a standard Version Cue project. You
can use the capabilitiesProvider extension point to do the following:
z Disable particular menu items within the Version Cue client user interface, by removing
some of the default project capabilities.
z Add capabilities to the default set, extending the functionality available at the client for a
particular project.
NOTE: To customize the capabilities of an external project, override
IProjectController.getResources(...), which can be used to return a custom set of
capabilities for an external project. The capabilitiesProvider extension point is relevant
only to standard Version Cue projects and is called only for standard projects.
Ta bl e 6 shows the fully qualified name of the extension point and the interface it must imple-
ment.
TABLE 6 Capabilities Provider Extension Point
Extension Point Required Interface
com.adobe.versioncue.controller.project.api.capabilitiesProvider IProjectCapabilitiesProvider
See the entry in the Extension Point Reference for the extension point with fully qualified name
com.adobe.versioncue.controller.project.api.capabilitiesProvider, as well as the API Reference
for com.adobe.versioncue.controller.project.api.IProjectCapabilitiesProvider.
To modify capabilities for an external project, you can do this from your implementation of
IProjectController.getResources(...). See sample.customproject for an example of an implementation of this being used to specify the capabilities an external project supports.
66
Extending the Version Cue SOAP protocol
Suppose that you have created some custom menu elements at the Version Cue client, such as
Adobe Bridge CS3, and you want to provide some new behaviour that can be parameterized by
Adobe Version Cue CS3 Server Programmer’s Guide
Version Cue Server Extensibility
the user; for instance, you want to perform some image processing operation on a selected
asset in Adobe Bridge CS3, using your own external system to compute the result, and pass in
parameters specifying the operation and how it is to be performed. Perhaps you want to
present a dialog (using the JavaScript/ ScriptUI library) to collect the parameters from the user
within the Version Cue client and then send these parameters over the network to the Version
Cue server.
To do this, you must extend the basic Version Cue SOAP protocol between the client and Version Cue Server, which you can do by using an extension point of the protocol manager layer.
You can use the extension point named generic call to contribute new methods to the SOAP
protocol between Version Cue clients and the Version Cue Server.
See the Extension Point Reference for details about the extension point. Ta bl e 7 shows the fully
qualified name of the extension point. Note that because you are implementing support for
your own entirely custom methods, you do not implement an existing interface, but you
should subclass GenericCallAdapter to support the server side of your additions to the SOAP
protocol. See sample.custommenu for an illustration of extending the Version Cue SOAP protocol and look for the classes named GenericXXX.
TABLE 7 SOAP Protocol Extension Points
Extension Point Required Interface
com.adobe.versioncue.soap.genericcall.genericCall <not applicable>, but you should subclass
GenericCallAdapter in the package
com.adobe.versioncue.soap.genericcall.manager
User Creation, Login and Authorization
There are extension points relating to the interaction of users with a Version Cue Server that
enable you to implement the following use cases:
z Dynamically creating users in the Version Cue model; for instance, you can retrieve details
about a user from an external system when they are logging in— this is constrained to certain fields that are known to Version Cue Server, but you can determine where the information to populate those fields comes from.
z Controlling whether certain users can log in or not; you can control authentication at the
Version Cue Server.
z Determining whether requests from particular users should be allowed or denied; you can
control request authorization at the Version Cue Server, say to delete particular assets.
It is possible for you to dynamically create users, for instance, with properties derived from
user profiles in an external system. You can also take control during the process of a user logging into a Version Cue project; that is, during the authentication process. There is an exten-
sion point (external user handler) that you can register on to let you take control when
dynmically creating users or authenticating users. If you register on this extension point, then
during a login attempt, your implementation of the IExternalUserHandler interface can be
sent a user/password, and you decide whether to authenticate or reject the user.
Adobe Version Cue CS3 Server Programmer’s Guide 67
Adobe Version Cue CS3 Server Programmer’s Guide
Version Cue Server Extensibility
Each time a user makes a request to Version Cue Server, if you register on the request validator
extension point, you can choose to allow or deny that user’s request in your implementation of
IRequestValidator. That is— you can control authorization of requests against the Version
Cue Server using this extension point.
See the Extension Point Reference for details about these extension points. Tab le 8 shows the
fully qualified names of the extension points and the interfaces they must implement.
TABLE 8 User-related Extension Points
Extension Points Required Interface
com.adobe.versioncue.webapp.externalUserHandler IExternalUserHandler
com.adobe.versioncue.webapp.requestValidator IRequestValidator
68
Adobe Version Cue CS3 Server Programmer’s Guide
Appendix
Additional Version Cue Server Model Diagrams
FIGURE 42 Unified Class Diagram for Containers, Assets, Files, and Versions
IModelObject
IVersionIdentity
IAssetIdentity
Appendix
IVersion
IAssetContainer
IProject IRootContainer
IAsset
IFileItem
IThumbnail
IVersionableAsset
IXMPMetadataILock
IFileIFileContainer
IFileRootContainer
Adobe Version Cue CS3 Server Programmer’s Guide 69
Adobe Version Cue CS3 Server Programmer’s Guide
Appendix
Figure 43 summarizes the key associations between projects, assets and versions.
FIGURE 43 Class Diagram of Associations between Project, Files and Versions
asset hierarchy
has file
containers
0..*
1
IFileContainer
IAssetContainer 1
has root container named files
IFileRootContainer
IAssetContainer 1
has folders
IAsset 0..*
has files
IAsset 0..*
IProject
1
1
1
has files
0..*
IFile
70
IThumbnail IXMPMetadata IAssetVersionProperty
version-level metadata
0..2
IVersionableAsset 1
has versions
IVersion
1
1..*
1
0..1
1
1
is locked
IAsset
ILock
0..*
0..1
Bibliography
z Booch, Rumbaugh and Jacobson, 1999. The Unified Modelling Language User Guide. Addi-
son-Wesley.
z D’ Anjou, Fairbrother, Kehn, Kellerman and McCarthy, 2004. The Java Developer's Guide
to Eclipse. Addison-Wesley.
z Eclipse online documentation http://help.eclipse.org/help32/index.jsp.
z Gamma, Helm, Johnson, and Vlissides, 1995, Design Patterns. Addison-Wesley.
z Lea D, 1999. Concurrent Programming in Java: Design Principles and Patterns (2nd Edi-
tion). Addison-Wesley.
z Lea, 2006. Doug Lea’s Home Page, accessed March 2006. http://gee.cs.oswego.edu/dl/.
z RFC 2396 Uniform Resource Identifiers. http://www.ietf.org/rfc/rfc2396.txt.
z RFC 2616 Hypertext Transfer Protocol: HTTP/1.1. http://www.ietf.org/rfc/rfc2616.txt.
z SOAP specification: http://www.w3.org/TR/soap/.
z Sun™ JSR 166 and also the Java Specification Request site at www.jcp.org.
Adobe Version Cue CS3 Server Programmer’s Guide
Appendix
Adobe Version Cue CS3 Server Programmer’s Guide 71
Adobe Version Cue CS3 Server Programmer’s Guide
Appendix
72
Adobe Version Cue CS3 Server Programmer’s Guide
Appendix
Adobe Version Cue CS3 Server Programmer’s Guide 73
Adobe Version Cue CS3 Server Programmer’s Guide
Appendix
74
Adobe Version Cue CS3 Server Programmer’s Guide
Appendix
Adobe Version Cue CS3 Server Programmer’s Guide 75
Adobe Version Cue CS3 Server Programmer’s Guide
Appendix
76
Loading...