Copyright © 2006 Board of Regents of the University of Wisconsin System (Univ. of Wisconsin-Madison, Trace R&D Center)
This tutorial is written for developers wishing to use the URC Software Development Kit for the implementation of Targets and/or Universal Remote Consoles, based on the ANSI standards of the URC framework. The reader is recommended to read through these standards (in ascendent order) before using the URC SDK.
The rest of this tutorial is organized into the following sections. The organization of the SDK describes the components of the SDK package, with regard to its file and directory structure. Next comes an overview of the Java packages of the SDK. Finally, the How-To section provides step-by-step courses for implementing targets and URCs based on the URC SDK. These courses are each provided as external documents, linked from this document.
This tutorial was developed with funding from NIDRR, US Department of Education under grants H133E980008, and H133E990006.
This section describes how the URC SDK is organized in terms of files and directories. We assume you have downloaded the sdk.zip file from the URC SDK project page and extracted its files to a local directory, let's say to C:\UrcSdk (this is not to imply that you have to use a Microsoft Windows operating system to use the SDK).
The SDK's root directory (this would be C:\UrcSdk on your local computer) contains general information on the URC SDK project at Trace. This includes the following files:
The dev directory (local C:\UrcSdk\dev) and its subdirectories contain the Java source code of the URC SDK. Under C:\UrcSdk\dev\src you find the Java packages that are provided by Trace (packages starting with "edu.wisc.trace.urcsdk") - see Java packages for more information on them. dev\lib contains 3rd-party code that is needed for running the URC SDK. dev\lib\int holds 3rd-party code that we are allowed to redistribute, and dev\lib\ext comes with Readme files for external libraries that we cannot redistribute. Please follow the instructions in the Readme files to download the individual code libraries.
The build.xml file (in the dev directory) is the build file for the URC SDK, as used by the Trace URC team. You will need to install the Apache Ant build tool if you want to use and modify it for your own purposes. Here is a short summary of what the build.xml file does. (However, using build.xml is not a requirement for using the URC SDK. You may use any appropriate tool to compile the source files.)
The doc directory (local C:\UrcSdk\doc) contains the generated Javadoc files. Open the index.html file as an entry point. The Javadoc documentation describes all public classes and interfaces, including public and protected fields and methods. You may use this documentation as a reference when developing code that uses the URC SDK.
The tutorial directory (local C:\UrcSdk\tutorial) contains this document and its sub-tutorials.
The Java packages of the URC SDK are stored under dev\src (local C:\UrcSdk\dev\src), with subdirectories reflecting the full package structure. For example, the source file for the class Constants in the packageedu.wisc.trace.urcsdk.base is stored as file dev\src\edu\wisc\trace\urcsdk\base\Constants.java.
The packages of the URC SDK include the source files (.java) for classes and interfaces, plus any resource files that are needed at run-time (e.g. xml files, images).
The URC SDK comes with support for Target developers and for URC (client) developers. There are packages that contain code for Targets, and packages that contain code for URCs. Packages can be further distinguished according to the software layer they are used in (see figure 1 below). Two packages (edu.wisc.trace.urcsdk.base and edu.wisc.trace.urcsdk.support) contain code that is used on both Targets and URCs.
Figure 1: Overview of the Java packages in the URC SDK. Package names are abbreviated ("edu.wisc.trace." prefix omitted). Textual diagram description available.
This package provides utility classes that are used throughout the entire SDK:
This package contains classes that are needed for the UPnP-2-Service-TUN link, for both target-side and client-side implementations.
This package has utility classes that are useful for Targets and URC, including:
This is the main package for URC (client) implementations. The most important classes and interfaces are:
URC implementers should read How to write a URC client in Java for more details.
Note: All interfaces in the SDK start with a captial "I" so you can easily differentiate them from ordinary classes.
The facade package contains the class FacadeForJs which provides methods for external calls from JavaScript code. With this class, one can use the SDK from any JavaScript code running in a Web browser, or from any Web-based plug-in, as long as it can access JavaScript code. For more information, refer to How to write a URC in Javascript or Flash.
This package contains classes of Interactors, as used in Presentation Templates. Implementers who want to implement a concrete renderer for a PreT can base their implementation on this package. Trace is providing an example of such an implementation with the edu.wisc.trace.urcsamples.swingurc package of the URC Simulation Environment (not part of the URC SDK).
This package contains classes for the resource manager that serves as a central resource serving point within the URC. It manages the Atomic Resources contained in Resource Sheets from the Target. Future versions of the SDK are planned to also support downloading resources from external resource servers and cache them locally.
This package contains classes for the URC-side UI socket (which is a mirror of the Target-side UI socket).
This package contains type implementations for the elements of a URC-side UI socket.
This is the client-side implementation of the UPnP-2-service TUN Link which defines a communication protocol between the Target and a URC based on the UPnP device architecture 1.0. Special (vendor-specific) device and service descriptions are included for the URC (URCDevice.xml, URCService.xml).
Note: These descriptions are vendor-specific as defined by UPnP. They do not constitute a standardized Device Control Protocol (DCP) in the UPnP forum.
This package implements an alternate TUN Link which is based on the UPnP Device Control Protocols (DCPs) that have been standardized in the UPnP forum. The Targets are native UPnP devices and don't know anything about the URC framework. So the URC has to make up for that and get the necessary URC-specific documents from a resource server (e.g. http://resources.myurc.org/) in lieu of the Target.
Note: Currently, this package supports the following UPnP devices only: Philips Media Manager (MediaServer) and Philips Streamium SL300i (MediaRenderer). Future versions of the SDK are planned to support more UPnP and DLNA devices.
This package contains the XPath parser implementation needed for the dependency specifications between socket elements in a Socket Description. We have used the JJTree tool to generate Java code from parsing rules, as specified in the file XPathParser.jjt.
Note: XPathParser.jjt is the only file that should be edited manually - all other files are generated.
This is the main package for Target implementations. The most important interfaces and classes are:
Note: Target implementers should read How to write a Target in Java for more details.
This package contains the class TargetFacadeForJni which provides an interface to non-Java target code contained in a DLL. Target implementers can use the URC SDK together with their C/C++/C# code. For more details refer to How to write a Target in C/C++/C#.
This package contains classes for the implementation of a Target-side user interface socket. Note that these are different classes than what is needed to implement the URC-side UI socket which is actually a mirror of the Target-side socket.
This is the Target-side implementation of the UPnP-2-service TUN Link which defines a communication protocol between the Target and a URC based on the UPnP device architecture 1.0. Special (vendor-specific) device and service descriptions are included for the Target (TargetDevice.xml, TargetService.xml).
Note: These descriptions are vendor-specific as defined by UPnP. They do not constitute a standardized Device Control Protocol (DCP) in the UPnP forum.
Last updated: Hemanth Vijayan, 2006-10-06