Channel ARchives

What They Are
Installation
Do They Require Different Code?
Building Them

Deployment Descriptors and Their Supported Tags

A Channel ARchive, or CAR, in its simplest form is just a java archive with a ".car" extension. They are created with the Jar utility provided with the Java SDK. CARs can contain all elements used for the construction and presentation of custom java channel types and their contents. A fully functional CAR is included here to illustrate their capability. (Note: Some browsers append ".zip" to this file upon downloading. Simply rename it to carlot.car.) This car contains a channel known as the CAR LOT. It shows what cars exist in the portal and shows their contents. It contains the source java file, the compiled class file, a stylesheet list file, an XSLT stylesheet, and two images that are served up to the browser from within the CAR.

You must have uPortal 2.1 or later to use CARs. You can publish CAR LOT using the following values.

In uPortal 2.2, CARs received the added capabilities of housing services and workers and being able to declare them using a deployment descriptor file. (See "What is a Deployment Descriptor?" later in this document.) A channel archive named deployTest.car containing a service, a worker, and an extension block can be obtained here. The deployTest.car archive does not contain a channel. Its sole purpose is to illustrate the power and use of the deployment descriptor support. You must have uPortal 2.2 or later for this archive to work. Upon installation and restarting the portal click on the following link to access the worker which will be automatically installed.

http://localhost:8080/uPortal/worker.com_sct_pipeline_uportal_channels_deployTest_HelloWorker.uP

This link assumes the portal is running on the local machine on port 8080. If it isn't, then replace the appropriate host and port in the URL. You'll notice that the returned page shows if the worker and service were installed and if the extension block of the deployment descriptor executed successfully.

Through these examples we see that CARs are containers that can house multiple channels, their resources, workers and services, and a deployment descriptor indicating what resources they contain so that in the case of workers and services the portal can instantiate and use them. CARs can be used to package up and deploy from a single channel, worker, or service to an entire channel application suite.

By default the portal looks in /WEB-INF/cars or any of its subdirectories for channel archives. To install a CAR simply place it in that directory or its subdirectories and restart the portal. Upon start up, the portal scans the cars directory structure for all CARs and loads internal tables with paths to each of the resources available from the archives. It also processes all extension blocks declared in any deployment descriptors found in the archives. (See "What is a Deployment Descriptor?" later in this document.)

If the portal is deployed in a container that uses a WAR file for deployment that container may not allow access to the default car directory in the WEB-INF directory. If such is the case or if you simply want to place your CARs in some other location you can define the following property in the portal.properties file with a fully qualified path to the location of the directory that will house your channel archives.

org.jasig.portal.car.CarResources.directory

The name of a channel archive has no affect on its contents or the use of those contents by the portal. If two CARs aquired from different sources but containing different components need to be deployed in the same directory, then simply rename one or the other prior to installing in the directory. Alternatively, you could create subdirectories beneath the car directory based on the java package directories of the provider of the CAR. Then the CARs can be placed into the appropriate subdirectories with their names unchanged.

Channels may require minor changes to be deployed in a CAR. For example, an image used in the channel and located in some subdirectory of the /media directory would most likely have an XSLT stylesheet with code like the following:

This would still be appropriate if the folder_delete.gif image were still located in the appropriate place beneath the media directory. But such an approach would negate one of the major goals of a CAR; namely to place all resources needed by a channel into the archive to prevent tight coupling between the stylesheet and a file located in some other directory. Such a deployment is susceptible to installation errors if the image is not located in the correct location or is subsequently deleted.

A better solution is to place the image in the CAR and modify the channel to obtain an appropriate URL for aquiring the image from the CAR. To do so typically requires calling one of three versions of a method in ChannelRuntimeData specifically designed to construct the base of this URL and then passing that value to the XSLT stylesheet for use in constructing the full URLs to the various images used by the channel.

ChannelRuntimeData has three methods to assist with constructing URLs appropriate for browsers to aquire resources out of channel archives. These are:

• getBaseMediaURL( Object aChannelObject )

• getBaseMediaURL( Class aChannelClass )

• getBaseMediaURL( String resourcePath )

The first two can be passed some object or class that is known to only be deployed with the channel. Typically, this is the channel itself. These two methods then look to see whether or not the class of the object was loaded from a CAR. If it was then the method returns a URL base that can be used to aquire images from a CAR. If the class was not loaded from a CAR, then the method returns the traditional URL base path for images namely, "/media.". The format for the URL base for CAR-accessible images is similar in form to:tag.idempotent.worker.carRsrc.uP?carRsrc=

As you can see the URL still needs a value appended indicating what car resource is desired. That value must be the path as found within the channel archive. For example, if you execute jar tf carlot.car you'll see that the car.jpg image has a path of com/sct/pipeline/uportal/channels/carlot/car.jpg. This would be the value to append to the base URL to allow the browser to aquire that image directly from carlot.car.

Note, the package relative directories are used not only for CAR LOT'S compiled class files but also for all of its resources. Like Java code in general all resources deployed in CARs should be placed in globally unique, package relative directories as specified in Java Language Specification, section 7.7. This is because all resources aquired from CARs share the same namespace. If CAR LOT didn't use package relative directories, then the path to its car.jpg image would consist only of the file name itself. The probability of contention between such a path in one CAR and an identical path to a similarly named but completely different image in another CAR would cause one of the two images to be served up in place of both and the other would never be accessible.