Oracle Programmer’s
Reference Guide
Database Java SDK for Oracle
Virage Incorporated
177 Bovet Road, Suite 520 (650) 573-3210 www.virage.com San Mateo, CA 94402-3121 (650) 573-3211 fax [email protected]
Virage, Inc., San Mateo, CA -
by Virage, Inc.
All rights reserved. Published 1999 Printed in the United States of America
June 22,
“Virage” and “PinPoint” are registered trademarks of Virage, Inc. “VideoLogger,” “AudioLogger,” “VIR Image Engine” and the Virage logo are trademarks of Virage, Inc.
All trademarks are the property of their respective owners.
Operation of this product is covered by U.S. Patent ,, licensed by Virage from IBM Corporation. Parts of the JPEG image read-write software is copyright 1991–95 by Thomas G. Lane. This software is based in part on the work of the independent JPEG group.
1 Introduction to Virage Database Java SDK 13
Terminology . . . 14
Database Java SDK product components . . . 14
Software developer kit . . . 15
Java SDK packages . . . 15
VDF data . . . 17
VDF data flow . . . 18
Independent operations . . . 19
2 vdf package 21 Overview of the vdf package . . . 21
Inheritance tree . . . 24 Changing VDF data . . . 25 Accessing VDF data . . . 25 VDF class . . . 25 SourceVideoInfo class . . . 26 Label class . . . 27 LabelSet class . . . 27 ProxyInfoList class . . . 28 TrackList class . . . 28 VDF Events . . . 29 3 db package 31 Overview of db package . . . 31 Inheritance tree . . . 32 Multi-threading . . . 32 Listing VDF objects . . . 33
VDFLister and VDFListParam . . . 33
Snapshot of VDFLister API . . . 34
VDFLister sample code . . . 35
Snapshot of VDFListParam API . . . 36
VDFListParam sample code . . . 37
Loading VDF objects . . . 37
VDFLoader and VDFLoadParam. . . 37
Snapshot of VDFLoader API . . . 38
VDFLoader sample code . . . 39
Snapshot of VDFLoadParam API . . . 39
VDFLoadParam sample code . . . 40
Writing VDF objects . . . 41
VDFWriter object . . . 41
Snapshot of VDFWriter API . . . 41
VDFWriter sample code . . . 42
A Sample package 45 HelloVDFLister sample. . . 45
HelloVDFLoader sample . . . 46
HelloVDFWriter sample . . . 46
B User interface sample packages 47 vdfvis sample package . . . 48
vdfvis package classes . . . 48
vdfvis package events . . . 49
vis sample package . . . 50
User interface and interaction. . . 50
Login . . . 50
List and select videos . . . 50
View the video data . . . 51
vis package classes . . . 51
1–1 Database Java SDK packages . . . 17
1–2 VDF data flow . . . 18
1–3 Java SDK interface and operations . . . 19
2–1 VDF object and its constituent data. . . 23
2–2 vdf package inheritance tree . . . 24
2–3 VDF event example . . . 29
3–1 db package class inheritance . . . 32
3–2 VDFLister class inheritance . . . 33
Welcome to the Virage Database Java SDK for Oracle Programmer’s
Refer-ence Guide. This document describes how to use the Virage Database Java
SDK for Oracle, a product that allows you to develop a solution to extract and view VideoLogger metadata stored on an Oracle Server.
This guide explains the components and operations of the Java SDK, the sample applications, and user interface packages. The programmer’s guide also includes information about VideoLogger, database plug-in for Oracle, and Java SDK operations. The information in this guide, for the most part, serves as a high-level overview of the Java SDK. For detailed information about classes, attributes, and methods, refer to the API Reference Documen-tation located in the Database Java SDK\Documentation\javadocs\ directory.
Virage also offers the VideoLogger SDK that supplies APIs that allow you to develop applications of your own design, as well as plug-ins for databases, not directly supported by Virage.
Audience
This programmer’s guide is written for software developers responsible for developing applications that retrieve data from the Virage Video Foundation
Schema. This guide assumes that you have knowledge and experience with the Java programming language, are familiar with the Virage Video Founda-tion Schema, and have experience setting up and administering relaFounda-tional databases.
Related Documents
Use the information and instructions in the Virage Database Java SDK for
Oracle Release Notes for installing and troubleshooting the Virage Database
Java SDK. Refer to the online HTML API Reference Documentation (java-docs) for detailed information about the classes, attributes, and methods that comprise the Java packages. You should also be familiar with the Data-base Plug-in for Oracle documentation, especially information about the Virage Video Foundation Schema.
Contacting Virage
Send questions about purchasing the Java SDK to
Contact our technical support staff if you have questions about using the Java SDK or suggestions for improving quality or functionality. Call
⁄- between :A.M. and :P.M., Monday through Friday, or
send email to
Some of your questions might be answered on our Web site. You can access our server at
Updates to the programmer’s guide
The latest version of the programmer’s reference guide is at the following URL. Check the print date on the copyright page to compare versions. Log in as ‘virage’ with a password of ‘virtu’.
1
Introduction to Virage
Database Java SDK
Chapter 1 introduces the Virage Database Java SDK for Oracle by providing an overview of the product, its components, and operations. The informa-tion in this chapter also helps you understand the relainforma-tionships among the Virage Database Java SDK, Database Plug-in for Oracle, and the VideoLog-ger application.
The Virage VideoLogger and AudioLogger log media to create metadata, also known as video indexes. The Virage Database Plug-in for Oracle pro-vides a method for storing the metadata in an Oracle database. The Java SDK provides a means for you to access and use the metadata stored in the Oracle database.
The Java SDK operates in a standard Java Virtual Machine environment, which you must have installed on the system you plan to use for develop-ment. The Java SDK uses Java Database Connectivity (JDBC), provided by Oracle, to establish a connection with the database. See the Virage Database
Java SDK Release Notes for installation and product requirements.
For a description of the Virage Database Plug-in for Oracle, operations, and product components, refer to the Virage Database Plug-in for Oracle
Admin-istrator’s Guide. And for information about VideoLogger operations refer to
the Virage VideoLogger User’s Guide.
Terminology
This guide uses the term VDF data, for the most part, instead of the terms
video index or metadata. However, all three terms represent the same
concept: data or information, generated by the Virage VideoLogger, that describes the contents of a video or other form of media.
Database Java SDK product components
The Virage Database Java SDK for Oracle supplies software development tools for creating solutions to access VDF data stored in an Oracle database. The Java SDK also provides sample packages that demonstrate the possibil-ities for developing your own applications, as well as API-level documenta-tion generated by the javadoc utility.
Software developer kit – supplies a set of Java classes that retrieve VDF data, using JDBC, from the database and displays it in a user interface. The Java SDK provides fundamental building blocks for developing more complex applications for viewing and browsing VDF data. The reusable Java classes can significantly reduce development time because they are designed specifically to handle complex video data types. Refer to chapter 2: “vdf package” and chapter 3: “db package” for additional information.
Sample packages – demonstrate how to use the Java classes for developing your own applications, as well as provide a foundation from which you can begin the development process. The samples are simple applications and user interfaces that demonstrate how to use the VDF objects,
data-base objects, and APIs (Application Program Interface). The sample applications run as client-side Java applications or applets and provide an immediate solution for viewing VDF data and using the APIs. Refer to appendix A: “Sample package” and appendix B: “User interface sample packages” for more information.
API Reference Documentation – describes the Java classes, attributes, and methods that constitute the product and sample applications. The docu-mentation consists of HTML files that comprise information or instruc-tions written during development and is generated by the javadoc utility. To access the developer documentation, double-click on the index.html file located in the Database Java SDK\Documentation\javadoc\ directory. The index.html launches a browser that includes a table of contents, where you can select any of the HTML files contained within that directory.
Software developer kit
The developer tools for the Virage Database Java SDK for Oracle include several Java packages comprised of classes which you can customize or use right “out of the box.”
Java SDK packages
The Java SDK consists of two packages or “groups of classes” that allow you to build your own applications for extracting and loading VDF data:
n vdf package – provides the VDF class that represents the VDF data stored
n db package – has three main classes: the VDFLister class retrieves a list
of videos, the VDFLoader class loads data for a specific video, and the VDFWriter class writes changed or modified video data to the database. The vdf and db packages provide a complete set of tools for you to develop your own search and browse applications. However, you can combine the software developer packages with the user-interface sample packages to cre-ate a complete solution as illustrcre-ated in Figure 1–1. The user-interface pack-ages provide the following functionality:
n vdfvis package – serves as an example of the GUI classes that
demon-strate how to view and browse VDF data for a single video in the data-base. The vdfvis package provides VDFViewer GUI classes that view the contents of a VDF object.
n vis package – serves as an example of the GUI classes that demonstrate
how to view and browse VDF data for all the videos in the database. The vis package consists of a login GUI, connection handler, and the VDFLister GUI classes. The vis package combines functionality of both the vdf and db packages, as well as the vdfvis sample package.
VDF data
If you are familiar with the Virage VideoLogger application and Database Plug-in for Oracle, then you are familiar with how VDF data is generated and stored. The Java SDK provides an object representation of VDF data, which is the core component of the product. A VDF object consists of the same data but in a Java environment.
Contents of a VDF object:
n Source video info n Video label n Proxy list
n Track list, for example: clip label, speech, speaker ID, closed caption, and
keyframes
Figure 1–1: Database Java SDK packages VDFLoader VDFLister VDF VDFListerAgent VDFViewer VDFListPanel VDFTreePanel VDFLoaderAgent vis package vdfvis package db package vdf package Interface VDFWriter
VDF data flow
The Virage VideoLogger generates VDF data and saves it in the Virage Video Foundation Schema (VVFS) provided by the Virage Database Plug-in for Oracle. Once the VDF data is in persistent storage, you can use the Java SDK to list and load the data.
Essentially, the Java SDK lists the VDF data, defines what data to retrieve, and then creates and loads the VDF data. Once the data is loaded, you have the ability to view, browse, and modify it if necessary.
Figure 1–2 illustrates the flow of VDF data.
Figure 1–2: VDF data flow VVFS Database Workstation JDBC plug-in VDFLoader VDFLister Interface VDF video video video video VideoLogger VDFWriter
Independent operations
Figure 1–3 illustrates how the vdf and db packages, Java SDK user interface, and retrieval operations are inherently independent. There are four compo-nents that form all Java SDK operations: vdf package, db package, and the two sample user interface packages. The Java SDK reusable classes foster independent operations by minimizing database dependencies.
Figure 1–3: Java SDK interface and operations VDF VDFListPanel VDFViewerPanel VDFLoaderAgent VDFListerAgent vdfvis package VDFTreePanel VDFLoader VDFLister VDFWriter JDBC/ VVFS vdf package db package vis package
The vdf and db packages are essential for developing a Java application that accesses and retrieves VDF data. However, the user interface sample pack-ages demonstrate how you might display VDF data in an interface.
The reusable Java classes can significantly reduce development time because they are designed specifically to handle complex video data types.
2
vdf package
Chapter 2 describes the Virage Database Plug-in for Oracle vdf package, including the most significant classes, attributes, and methods for handling VDF data. However, for a complete description of all vdf package classes, attributes, and methods, refer to the API Reference Documentation located in the Database Java SDK\Documentation\javadoc\ directory.
Overview of the vdf package
The vdf package, com.virage.vdf, is a collection of classes that represent VideoLogger metadata (VDF data). A VDF object, stored in memory, is an aggregation of the instantiated classes that represent the VDF data. The vdf package defines the Java implementation of VDF data. See Figure 2–1 for a representation of a VDF object and its constituent data.
All operations performed on a VDF object only affect the object, not the original source VDF data from which the object was loaded. There is no connection between a VDF object and the data in the database. The follow-ing attributes define a VDF object:
n Unique ID – numeric ID of the VDF object n Duration – duration of the VDF object
n Owner – owner of the VDF object
n Log date – when the VDF object was created
The following classes comprise the VDF package:
n SourceVideoInfo – various properties of the video used to create the
VDF. This information is implemented by the
com.virage.vdf.SourceVideoInfo class. This class provides methods for using the various capture parameters of the source video.
n Label (video) – user annotation describing the contents of the entire
VDF object (video). The video label is implemented using an instance of the com.virage.vdf.Label class.
n LabelSet – label set associated with the VDF object. A label set has a
sin-gle attribute, its name. The label set is implemented using an instance of the com.virage.vdf.LabelSet class.
n ProxyList - contains one or more media proxies associated with the
VDF object. The Virage Video Foundation Schema defines the default proxy which, if you choose, you can change. This information is repre-sented by the com.virage.vdf.ProxyList class.
n TrackList – contains the most important aspect of cataloged media, a
list of tracks. Tracks are time-based data generated by the VideoLogger. A track is a list of records, each record containing some data associated with a time span in the source video. Tracks are classified into these cate-gories:
n text tracks (com.virage.vdf.TextTrack class) – contains a list of
TextTrackRecords (com.virage.vdf.TextTrackRecord)
n image tracks (com.virage.vdf.ImageTrack class) – contains a list
n label tracks (com.virage.vdf.LabelTrack class) – contains a list of
LabelTrackRecords (com.virage.vdf.LabelTrackRecord) The vdf package contains the classes that implement a VDF object.
Figure 2–1: VDF object and its constituent data VideoLabel VDF SourceVideoInfo ImageTracks -KeyframeTrack -CompressedKeyframe LabelTracks -ClipLabelTrack TextTracks -Closed caption -Speech -User defined -Audio . . . TrackList ProxyInfoList
Inheritance tree
The classes in the vdf package use standard Java inheritance methodology. The vdf package and its constituent classes share the following properties:
n Maintain a reference to their container
n Mark themselves and their containers changed when a set() method is
called
This functionality is implemented in the abstract ChangeableElement class. Every class in the vdf package inherits from the ChangeableElement class. Figure 2–2 illustrates vdf package inheritance relationships.
Figure 2–2: vdf package inheritance tree ChangeableElement ChangeableList TrackRecord Label VDF ProxyInfo SourceVideoInfo ProxyInfoList LabelTrackRecord TrackList ImageTrackRecord TextTrackRecord Track ImageTrack LabelTrack TextTrack KEY Class
There are a few collection type classes in the vdf package: ProxyInfoList, Track and TrackList. These collection type classes inherit from the ChangeableList abstract class, which in turn inherits from the Change-ableElement class. The ChangeableList class is updated every time an object is added, updated, or removed from the list
Changing VDF data
The vdf package allows you to change any of its constituent data using the predefined methods. The set() method for example, setX( X x ), changes the element in context and, at the same time, marks that object as changed. The collection type classes, namely ProxyInfoList, TrackList, and Track use the set(), add(), and remove() elements to maintain a list of changes.
Accessing VDF data
Accessing VDF data requires using the different methods defined for each class in the vdf package.
VDF class
A VDF class serves as a container for the VDF data that defines a video or other form of media.
VDF objects:
n SourceVideoInfo n Label (video) n LabelSet
n ProxyInfoList n TrackList
In most cases, to extract a VDF attribute, you only require the get()type method. All set() type methods are provided for advanced use by the vdf package. Although it is safe to use the set() type method, it’s rarely neces-sary.
To obtain the following VDF object data, use the get() type methods:
n Unique ID n Duration n Owner n Log date
SourceVideoInfo class
The SourceVideoInfo class is a collection of video capture parameters for the source video. Access SourceVideoInfo attributes by using simple get() calls.
For example: ...
SourceVideoInfo src.vid = my_vdf.getSourceVideoinfo(); int width = src_vid.getWidth();
int height = src_vid.get Height(); ...
Label class
A Label class allows you to modify field definitions for a video label. To obtain fields and their annotation values for a video label, retrieve the video label from the VDF object and the number of fields associated with the label. Once you know the number of fields, loop through the label, retrieving all the fields and reading the name and value of each field.
For example: ...
Label vid_label = loaded_vdf.getVideoLabel(); int n_fields = vid_label.size();
for (int i_field = 0; i_field < n_fields; i_field++) {
Field field = vid_label.get(i_field); String name = field.getName();
Object value= field.getValue();
System.out.println(name + ":" + value); }
...
You can also retrieve a field by using a specific field name.
LabelSet class
The LabelSet class has only one attribute, its name. Access the name by using the getName() method. Access LabelSet attributes by using simple get() calls.
For example: ...
string label_set_name = my_vdf.getLabelSet().getName(); ...
ProxyInfoList class
The ProxyInfoList class stores the video proxies. It also identifies and records the default proxy for a VDF object. To retrieve all proxy information, retrieve the size of the list, and then loop through the list to retrieve the information for each proxy.
If you know the proxy URL, you can also use it to retrieve the video proxy information.
For example: ...
ProxyInfoList proxy_list = my_vdf.getProxyInfoList() ...
ProxyInfo default_proxy = proxy_list.getDefault(); String default_proxy_url = defaultproxy.getURL(); ...
TrackList class
The TrackList class encapsulates a list of tracks and provides methods to perform the following operations:
n Register new tracks
n Retrieve a track using its unique ID n Add data to a track
To retrieve a track: ...
Track track = track_list.getById(track_id); ...
This example code returns the reference to the track if the track is registered in the track list.
To register a new track, you need to know the track ID, track name, and the track type:
...
track_list.registerTrack (track_id, track_name, track_type); ...
This example code returns true if the registration was successful. To add data to a track, use one of these methods:
n Use the call() method to add TrackRecord to a TrackList object n Retrieve the track and directly add data to it
VDF Events
A VDF object generates event objects that are used to notify other applica-tions that a VDF event has occurred. A change in a VDF object fires off an event and sends it to the listener (ChangeListener).
Figure 2–3 illustrates how a VDF event occurs.
Figure 2–3: VDF event example <Object>ChangeListener
<Object>
For example, if you made several corrections to a closed-caption TextTrack object, it generates a TextTrackChangeEvent. The TextTrackChan-geEvent communicates the change to the appropriate application when it “hears” or receives notice.
All VDF object components generate event listeners:
n SourceVideoInfo n Label (video) n ProxyInfoList n ProxyInfo n TrackList n Track n ImageTrack n LabelTrack n TextTrack
You can register any event listener with VDF, which VDF delegates to the appropriate object. Or you can register an event listener directly with a VDF object, for example, TextTrack.
To add or remove listeners:
“add” or “remove” <name>Listener( <name>Event evt ) For example:
3
db package
Chapter 3 provides an overview of the Virage Database Java SDK for Oracle db package. This chapter also contains sample code and API “snapshots” for each main class, as well as an explanation about db package inheritance rela-tionships. However, for a complete explanation of all db package classes, attributes, and methods, see the API Reference Documentation located in the Java SDK\Documentation\javadoc\ directory.
Overview of db package
The Java SDK db package, com.virage.db, implements the VDFLister, VDFLoader, and VDFWriter classes. These Java SDK classes are responsible for listing and loading data from, and for writing VDF data to the Oracle database. These three classes access the Oracle database by using OraVD-FLister, OraVDFLoader, and OraVDFWriter classes, respectively. The following steps describe the order in which db package operations occur:
.Use the VDFLister class to list all videos stored in the database.
.Select a single video (VDF) from the list.
.View and make changes to the data using the VDF accessor methods.
.Use the VDFWriter class to write or save any modifications or additions to the database.
Inheritance tree
The OraVDF classes inherit from the three main abstract classes contained in the db package. See Figure 3–1 for a representation of the db package class inheritance.
Multi-threading
The VDFLoader, VDFLister, and VDFWriter classes implement the Runna-ble method. Use the abort() method to halt processing at any time. For an example of multi-threading, look at the
com.virage.vis.Loader-Agent.java method in the API Reference Documentation. Figure 3–1: db package class inheritance
OraVDFLister KEY Class Abstract classes VDFLister OraVDFLoader VDFLoader OraVDFWriter VDFWriter Inheritance
Listing VDF objects
The VDFLister class implements the VDFLister object. The VDFLister object, by default, lists all of the videos stored in the database. You can, how-ever, modify the VDFLister class behavior to display a specific range of vid-eos.
VDFLister and VDFListParam
The VDFLister, an abstract class, generates a list of videos currently stored in the database. The VDFLister implements the OraVDFLister to retrieve and list the video data from the Virage Video Foundation Schema. The VDFListParam, consisting of VDFLister parameters, specifies which videos to list, by defining a range of dates. Figure 3–2 illustrates VDFLister class inheritance.
Figure 3–2: VDFLister class inheritance
KEY Class Abstract classes VDFListParam VDFLister OraVDFLister Inheritance aggregation
Snapshot of VDFLister API
This section contains a snapshot of the VDFLister API. See the VDFLister API Reference Documentation for a complete description of all associated classes, attributes, and methods.
...
//Factory method should be used to create lister objects. public static VDFLister getInstance( String
lister_class_name )
/*This method sets parameters to execute a query to get the list of VDFs based on the defined constraints.*/
public void setVDFListParam( VDFListParam lister_param ) public VDFListParam getVDFListParam()
//set the JDBC connection and, optional, progress callback. public boolean setConnection( Connection connection ) public boolean setProgressCallback( ProgressCallback ) //Methods to execute VDFLister.
public void run()
public boolean execute( Connection connection, ProgressCallback progress ) throws SQLException
//To get the data out of VDFLister. public int size()
public VDF get( int vdf_idx ) public VDF getVDFByID( int vdf_id ) ...
VDFLister sample code
Following is a code example that demonstrates how to use the VDFLister class:
...
// Create a VDFLister object VDFLister vdf_lister = null;
vdf_lister = VDFLister.getInstance(VDFLister.ORACLE()); try
{
rc = vdf_lister.execute( connection, progress ); }
catch( SQLException e ) {
System.out.println( e.toString()+"Load List Error" ); e.printStackTrace();
}
// The following section of code first gets the size of // vdf list and then loops thru the list of videos // printing the video id.
if( rc == true ) {
int n_vdf = m_vdf_lister.size(); for( int i= 0; i< n_vdf; i++ ) {
VDF vdf = m_vdf_lister.get( i ); if( vdf != null )
System.out.println( "vdf no: " +i+" has id: "+ vdf.getID() ); }
} else
System.out.println( "vdf no: " + i + " is null " ); ...
Snapshot of VDFListParam API
The VDFListParam class helps retrieve a list of VDF from the database. You can obtain a VDF list based on the following parameters:
n Number of VDFs n Range of dates for VDFs
For example: ...
//Sets the maximum number of VDFs to retrieve and list. void setMaxVDFCount( int max_vdf_count )
//Returns the number of VDFs to retrieve and list. int getMaxVDFCount()
//Clears the previous setting of the MaxVDFCount. void clearMaxVDFCount()
//Specifies a range of dates for listing VDFs.
boolean setBetweenDates( java.sql.Date from, java.sql.Date to )
//Gets the “from” date in the date constraints. date getFromDate()
//Gets the “to” date in the date constraints. date getToDate()
//Gets the specified range of dates of the VDF list. boolean isBetweenDates()
//Clears the range of dates. void clearBetweenDates() ...
VDFListParam sample code
The following section of code demonstrates how a VDFListParam can retrieve 100 VDFs created between Thanksgiving day and New Year’s day: ...
VDFListParam my_param = new VDFListParam(); // by deafult load all data
// load all the tracks except KEYFRAME and COMPRESSED_KF. my_param.setMaxVDFCount( 100 );
my_param.setBetweenDates( thanks_giving, new_year ); ...
Loading VDF objects
The VDFLoader class implements the VDFLoader object. The VDFLoader object implements the OraVDFLoader, to retrieve the video data from the Virage Video Foundation Schema.
VDFLoader and VDFLoadParam
The Java SDK uses the VDFLoader, an abstract class, to load VDF data for a single video in to a VDF object. The VDFLoadParam, consisting of VDF-Loader parameters, specifies the data to be loaded in the VDF object. See
Figure 3–3 for a diagram that illustrates VDFLoader class inheritance. Two steps are required to load data into a VDF object:
n Prepare a list of the data you want to load n Use the execute() method to load the data
Snapshot of VDFLoader API
This section contains a snapshot of the VDFLoader API. See the VDFLoader API Reference Documentation for a description of all associated classes, attributes, and methods.
//Use the factory() method to create VDFLoader objects. static VDFLoader getInstance( String loader_class_name ) //Executes a database query to load the data specified into //the VDF object passed in.
boolean execute( java.sql.Connection connection,
VDFLoadParam vdf_param, VDF vdf, ProgressCallback progress ) public void run()
public void abort )
void setConnection( java.sql.Connection conn )
boolean setLoaderCallback( LoaderCallback loader_clbk ) boolean setProgressCallback( ProgressCallback progress_clbk ) void setVDF( VDF vdf )
void setVDFLoadParam( VDFLoadParam vdf_param )
boolean set( java.sql.Connection connection, VDFLoadParam vdf_param, VDF vdf, ProgressCallback progress )
//This function implements Runnable for threads. Useful with //threads.
void run()
Figure 3–3: VDFLoader class relationships
KEY Class Abstract classes VDFLoadParam VDFLoader TrackRecordLoader OraVDFLoader Inheritance Aggregation
VDFLoader sample code
The following segment of code illustrates how to load data into a VDF object:
...
//Load all the data into the vdf - default. VDFLoadParam vdf_load_param = new VDFLoadParam(); //Create a new VDF and set its ID to 10.
VDF target_vdf = new VDF(); target_vdf.setID( 10 ); //Create a loader object. VDFLoader vdf_loader = null;
vdf_loader = VDFLoader.getInsance ( VDFLoader.ORACLE ); try { rc = vdf_loader.execute( connection, vdf_load_param, target_vdf, null ); } catch( SQLException e ) {
System.out.println( e.toString() "Load VDF Error" ); e.printStackTrace();
} ...
Snapshot of VDFLoadParam API
The VDFLoadParam class defines the list of VDF attributes to be retrieved from the database. Table 3–1 lists the types of VDF data you can load and where to find specific instructions for loading data in the API Reference Documentation.
VDFLoadParam sample code
Use the VDFLoadParam object to determine which track data to load in to a VDF object. The following sample illustrates how to leave, for example, the keyframe track out of a VDF object.
...
VDFLoadParam my_param = new VDFLoadParam(); // by deafult load all data
//Load all the tracks except KEYFRAME and COMPRESSED_KF. my_param.setIgnoreTrack( Track.KEYFRAME );
my_param.setLoadTrack( Track.KEYFRAME );
my_param.setIgnoreTrack( Track.COMPRESSED_KF ); ...
You create two separate lists for loading track data: a list for the tracks you do not want to include in the VDF object, and a list of tracks you do want to include. This makes it possible to add the same track to both lists. However, the list of tracks not included in a VDF object always takes precedence.
Table 3–1: Parameters for defining VDF attributes Load parameter API Reference Documentation all VDF data see setLoadAllData
video label see setVideoLabel label set definitions (video/clip) see setLabelSet
source video info see setSourceVideoInfo proxy info see setProxyInfo load all or no track data see setLoadAllTrack
no track data see setLoadTrack and setIgnoreTrack keyframe track without loading
the images
see setLoadNoImage (Useful in lazy load-ing of images.)
specific timespan for any track see setTimeSpan
Writing VDF objects
The VDFWriter class implements the VDFWriter object. Use the VDFWriter to write VDF data that has modifications or additions to the database.
VDFWriter object
The VDFWriter object provides the capability to modify VDF data already stored in the database. You can, for example, change the URL for a proxy, change the name of a field, or correct spelling errors in a closed-caption text track.
Snapshot of VDFWriter API
This section contains a snapshot of the VDFWriter API. See the VDFWriter API Reference Documentation for a thorough explanation of all related classes, attributes, and methods.
...
//Factory method should be used to create lister objects. public static VDFWriter getInstance( String
writer_class_name )
//Set the writer callback.
public boolean setWriterCallback( WriterCallback writer_clbk ) public boolean setProgressCallback( ProgressCallback
progress_clbk )
public boolean setConnection( Connection connection ) throws SQLException
public boolean setVDF( VDF vdf )
/*Set the operation to be performed should be one of the VDFWriter.ADD, VDFWriter.REMOVE, VDFWriter.UPDATE. */ public boolean setOperation( int operation )
//This function implements Runnable for threads. public boolean execute( int operation,
Connection connection, VDF vdf ) throws SQLException public void run()
public void abort ) ...
VDFWriter sample code
The following segment of code illustrates how to write VDF data to the data-base:
...
boolean rc = true; //Load vdf.
//See vdf loader sample for top loading a vdf from db. VDF my_vdf = new VDF();
loadMyVDFFromVDFLoader( my_vdf ); //Change stuff in vdf.
my_vdf.getSourceVideoInfo().setWidth( 640 ); my_vdf.getSourceVideoInfo().setHeight( 480 ); //Use the factory methods to create objects. VDFWriter vdf_writer = null;
vdf_writer = VDFWriter.getInstance( VDFWriter.ORACLE ); //Go to the DB and update data to the vdf.
try {
//create JDBC Connction Connection my_connection =
DriverManager.getConnection( db_conn, user, pass ); rc = vdf_writer.execute( VDFWriter.UPDATE,
my_connection, my_vdf );
} catch( SQLException e ) { System.out.println(e.toString()+"Update VDF Error" ); e.printStackTrace(); } ...
A
Sample package
This chapter describes the Java SDK sample package, com.virage.sam-ples. This package demonstrate the use of the vdf and db packages to load and list data from, and write data to the database. See the appropriate chap-ters for more information about the vdf and db packages. For a complete description of classes, attributes, and methods, see the API Reference Docu-mentation located in the Database Java SDK\Documentation\javadoc\ directory.
HelloVDFLister sample
The HelloVDFLister sample (com.virage.samples.HelloVDFLister) represents a simple application that lists VDF data. The HelloVDFLister sample uses the two core packages provided by the Java SDK: db and vdf. To compile the program, enter
javac HelloVDFLister.java To run the program, enter
java com.virage.samples.HelloVDFLister <db_user> <db_password> <jdbc connection_url>
HelloVDFLoader sample
The HelloVDFLoader sample (com.virage.samples.HelloVDFLoader) illustrates how to load video data into a VDF object by creating a default LoadParam object. The HelloVDFLoader sample uses the Java SDK db pack-age.
To compile the program, enter javac HelloVDFLoader.java To run the program, enter
java com.virage.samples.HelloVDFLoader <db_user> <db_password> <jdbc connection_url> <vdf_id>
HelloVDFWriter sample
The HelloVDFWriter sample (com.virage.samples.HelloVDFWriter) loads and changes VDF data. This sample creates a default LoadParam object that loads all the contents of the VDF, and then it updates the label, closed-caption text track, clip image track, and so forth. This sample also adds new clips to the VDF object. The HelloVDFWriter sample uses the Java SDK db and vdf packages.
To compile the program, enter javac HelloVDFWriter.java To run the program, enter
java com.virage.samples.HelloVDFWriter <db_user> <db_password> <jdbc connection_url> <vdf_id>
B
User interface sample packages
This chapter provides an overview of the two user interface sample packages included with Java SDK. You can use these packages unchanged or modify them to fulfill specific requirements.The Java SDK provides these two user-interface sample packages:
n vdfvis package n vis package
Each package has a distinct set of functionality. You can combine them to create a robust solution or use them separately and alter them as your requirements dictate.
For a complete description of classes, attributes, and methods, see the API Reference Documentation located in the Database Java SDK\Documenta-tion\javadoc\ directory.
See Figure 1–1 for a depiction of the user-interface sample packages and their relationship to the vdf and db packages.
vdfvis sample package
The vdfvis sample package (com.virage.vdfvis) serves as an example of the GUI classes that enable you to visualize VDF data for a single video. The vdfvis sample displays the following VDF data:
n Source video info n Video label n Proxy list
n Track list, for example: clip label, speaker ID, or keyframes
vdfvis package classes
The vdfvis package contains the following classes:
n VDFViewerPanel – panel that displays the contents of a VDF
n TestVDFViewerPanel – simple usage scenario for the VDFViewerPanel n ImageTrackPanel – GUI component that displays the content of an
image track
n LabelPanel – GUI component that displays the content of a label n LabelTableModel – table model that displays the video label
n LabelTrackPanel – GUI component that displays the content of a label
track
n LabelTrackTableModel – table model that displays the label track n ProxyInfoListPanel – GUI component that displays the content of a
n ProxyInfoListTableModel – table model that displays the proxy info
list
n SourceVideoInfoPanel –panel that displays the source video info n SourceVideoInfoTableModel – table model that displays the source
video info
n TextTrackPanel – GUI component that displays the content of a text
track
n TextTrackTableModel – table model that displays the content of a text
track
n VdfVisConsts – defines various constants used in the vis package
vdfvis package events
The vdfvis package utilizes the vdfvis event package (com.virage.vdf vis.event), which contains all the class files that generate events: Interface summary:
n TimeSpanSelectionListener – classes interested in listening to
time-span selection should implement this class
n VDFSelectionListener – classes interested in listening to VDF
selec-tion should implement this class Class summary:
n TimeSpanSelectionEvent – provides mechanism for time-based
events
n VDFSelectionEvent – provides mechanism for communicating VDF
vis sample package
The vis sample package (com.virage.vis) utilizes the vdfvis sample as well as all of the Java SDK packages. By incorporating the functionality of the vdfvis package, the vis package is able to display all the VDF data for a single video as well as this additional functionality:
n Provides for user login n Displays a list of all videos n Displays label sets
n Loads vdf data
User interface and interaction
The sample user interface provides for these three main interactions:
n Login
n List and select videos n View the video data
Login
You must first log in before you can use the vis sample package. Enter the connection information, user name, password, and database connection. Use the database connection specific to the JDBC driver used for the data-base.
List and select videos
Upon successful login to the database, the list of videos retrieved from the database are displayed in the GUI. To see details for a specific video, double click on the video row. The details of the selected video are displayed in the same window, which allows you to continue viewing the entire list of videos.
View the video data
When you double-click on a video in the video list, the VDFViewerPanel displays the following data for the selected video:
n Source video info n Video label n Proxy list
n Track list, for example: clip label, speaker ID, or keyframes
vis package classes
The vis package contains the following classes:
n The VideoViewerPanel – main user interface component that displays
all track data
n CompressedKFLoaderAgent – loads compressed keyframes on
TimeSpanSelectionEvent
n LoginAgent – establishes the JDBC connection
n LoginDialog – creates a customized dialog box for obtaining the login
info from the user
n VDFListerAgent – executes a thread to load the VDF list from the
data-base
n VDFListPanel – displays a list of VDFs from the database n VDFListTreePanel – displays a tree of VDFs from the database n VDFLoaderAgent – loads a VDF from the database
n VideoViewerApplet – uses VideoViewerPanel as an applet
n VideoViewerAppletinBrowser – uses VideoViewerPanel as an applet
inside the browser
n VideoViewerPanel – main container panel
n VisConsts – defines various constants used in the vis package
vis package events
The vis package utilizes the vis event package (com.virage.vis.event) which contains all the class files that generate events:
Interface summary
n VDFListLoadListener – used by classes that want to listen to the list
load event Class summary
n ConnectionEvent – LoginAgent establishes the connection and fires
this event
n VDFListLoadEvent – VDFListerAgent loads the list from the database
This Glossary contains terminology that describes the actions, structure, and principles of the Virage Database Java SDK for Oracle and associated media and products. Understanding these terms will help you with the information in this guide and make it easier to use the product.
Application Program Interface (API) calling conventions by which an application program accesses other applications, services, or operating systems. An API is defined at source code level and provides a level of abstraction between applications to ensure the portability of the code. Asset ID unique system-generated numeric identification (ID) used to
identify assets (video or clip) in the system. Each asset ID is unique within the database: no two assets can share the same asset ID. Audio track contains profile information about the audio track along
with synchronizing time codes. The VideoLogger application requires the Virage AudioLogger to generate audio track.
Clip time delimited segment of video; the VideoLogger uses the term clip to denote an arbitrary segment of video defined simply by an in-time and out-time. You apply clip annotations to a clip.
Clip label contains the in- and out-time codes identifying the clips and the related field annotation data entered by a user. A database
adminis-trator can customize the fields for clip labels so a user can accurately describe the clip contents.
Closed captioning text that was encoded in the original video signal, usually a transcription of spoken dialogue.
Closed-caption track contains line- captioning information from the source video along with synchronization time codes. In Europe, it simi-larly serves to contain the teletext data.
Field definitions used to annotate video and clip labels. Fields comprise a name and an arbitrary number of field properties. If the VideoLogger uses a filesystem plug-in, fields are defined in the schema.txt file by a user. If the VideoLogger application uses a database plug-in, fields are defined by a database administrator and stored in the database schema. Java applet small application created with the Java programming
lan-guage that runs inside a Web browser.
Java Virtual Machine (JVM) Acts as an execution environment for interpreting the Java programming language. Each operating system runs a unique Java Virtual Machine to translate Java code.
Keyframe still image generated and time stamped for a specific video asset. You can select a single keyframe or multiple keyframes to define a clip.
Keyframe track contains the keyframe images from the source video along with time codes identifying when the keyframes occurred in the video.
Label individual video or clip label that derives its definition from an arbitrary number of fields. With a database plug-in, fields and label sets are linked together by a video or clip label.
Label set named set of templates that comprise label definitions for vid-eos and clips. A label set contains definitions for a single video label and definitions for an unlimited number of clip labels. You can create multi-ple label set definitions, each with a unique name. If the VideoLogger application uses a filesystem plug-in, the label sets are defined by a user in the schema.txt file. If the VideoLogger uses a database plug-in, the label sets are defined by a database administrator and stored in the data-base schema.
Java Database Connectivity (JDBC) Java database-independent speci-fication, installed on a client system, that enables access to most major databases.
Source video original video used for logging data with the VideoLogger application.
Speaker identification track contains the names of the speakers partic-ipating in the audio track of the source video along with synchronizing reference information in time codes. The VideoLogger requires the Virage AudioLogger to generate speech identification track.
Speech-to-text track contains text interpreted from the audio track of the source video along with synchronizing reference time codes. The VideoLogger application requires the Virage AudioLogger to generate speech-to-text track.
Text track type of annotation, represented as an in-time and an out-time that associates a string of text with a period of logged video. Closed cap-tioning is the most common form of text track; other types can include speaker ID and speech-to-text translation.
Video label contains the field annotation data about the video source entered by a user in the video label fields. A database administrator can
customize the fields for video labels so a user can accurately describe the video contents.
Video proxy digital proxy for an analog source generated by a video encoder. A video proxy provides a user with the capability of viewing videos online. The database schema (Virage Video Foundation Schema) stores proxy metadata.
Virage Video Foundation Schema (VVFS) database schema developed by Virage to store VideoLogger metadata. The video foundation schema provides a foundation for building video cataloging and search applica-tions. The SQL scripts provided by the database plug-in install the video foundation schema on the database server.
A
accessing vdf data 25 adding
data to a track 28 event listeners 30
API Reference Documentation 15 APIs VDFLister 34 VDFListParam 36 VDFLoader 38 VDFLoadParam 39 VDFWriter 41 attributes, VDF object 21
C
ChangeableElement abstract class 24 ChangeableList abstract class 25 changing data, vdf package 25 classes
db package 33 vdf package 25 vdfvis package 48 vis package 51
compiling sample applications 45, 46
D
data flow description, VDF 18 data, accessing 25
database schema, Virage 56 db package inheritance 32 listing VDF objects 33 loading VDF objects 37 multi-threading 32 operations 31 writing VDF objects 41 displaying video data 48, 50
E
events vdf package 29 vdfvis package 49 vis package 52 extracting VDF attributes 26F
fields, obtaining 27H
HelloVDFLister sample application 45 HelloVDFLoader sample application 46 HelloVDFWriter sample application 46
I
inheritance db package 32 vdf classes 24
J
Java Database Connectivity (JDBC) 13 Java SDK
operations 19 overview 13
javadocs 15
L
Label class 22 LabelSet class 22 list and select videos 50 listing VDF objects 33 loading data in VDF object 37 login for user interface 50
M
multi-threading, db package 32
O
obtaining
fields and annotations 27 VDF object data 26 operations db package 31 Java SDK 19 overview, Java SDK 13
P
packages db 31 sample applications 45 sample user interfaces 47 vdf 21ProxyList class 22
R
register new tracks 28 removing event listeners 30 retrieving
field data 27 tracks 28
VDF object data 26
running sample applications 45, 46
S
sample application package 45 sample code VDFLister 35 VDFListParam 37 VDFLoader 39 VDFLoadParam 40 VDFWriter 42
save changes to VDF objects 41 software developer kit 15 SourceVideoInfo class 22 support 10, 11
T
terminology 14 TrackList class 22, 28 tracks, adding data 28
U
user interface sample packages 47 user interface, login 50
V
VDF data accessing 25
data flow description 18 defined 17
loading object 37 obtaining object data 26 viewing 51 VDF events 29 VDF objects attributes 21 contents 17 extracting attributes 26 listing 33
writing changes to database 41 vdf package
changing data 25 event listeners 30 inheritance 24
loading VDF objects 37 VDFLister class 33 VDFListParam class 33 VDFLoader class 37 VDFLoadParam class 37 vdfvis event package 49 vdfvis package
classes 48 events 49 overview 48 VDFWriter class 41
video foundation schema 56 videos
list and select 50 view data 51
Virage, Video Foundation Schema, defined 56 vis event package 52
vis package classes 51 events 52 overview 50