Becoming a Channel Archive Master, It’s as easy as ‘abc’

Becoming a Channel Archive Master, It’s as easy as ‘abc’ Mark Boyd Software Engineer/Architect mboyd@sungardsct.com

What We Will Cover u What is a CAR and how is it installed? What is the Development Impact? How do you build them? What is a Deployment Descriptor? Converting Classifieds Questions?

What is a CAR? • CAR = Channel Archive • Jar file format • Extension of “.car”. Is case sensitive. • Contains all channel artifacts used by the channel. • Contained files should be in package relative sub-directories. • Class files • Images • Stylesheets • Stylesheet Lists • XML files • Properties files • Deployment Descriptor • Other resources

A Look Inside jar tf carlot.car <META-INF/…> <Directories….> com/sct/pipeline/uportal/channels/carlot/car.jpg com/sct/pipeline/uportal/channels/carlot/Channel.java com/sct/pipeline/uportal/channels/carlot/channel.jpg com/sct/pipeline/uportal/channels/carlot/channel.ssl com/sct/pipeline/uportal/channels/carlot/stylesheets/channel.xsl com/sct/pipeline/uportal/channels/carlot/Channel.class

Non-CAR Channel Installation uPortal Root Directory Images WEB-INF Stylesheets and Stylesheet lists classes media Classes Configuration files stylesheets Note: package relative sub-directories not shown

Channel Installation with CARs(non-warfile deployment) uPortal Root Directory Images WEB-INF Stylesheets and Stylesheet lists classes cars media Classes MyChannel.car Configuration files stylesheets

Channel Installation with CARs(deployed as warfile or custom car location required) protal.properties org.jasig.portal.car.CarResources.directory=SomeDirPath/cars Images Stylesheets and Stylesheet lists Classes SomeDirPath MyChannel.car cars Configuration files

Channel Installation with CARs • CARs can be located in any sub-directory of the “cars” directory. • 2) The name of a car has no impact on its internal classes and artifacts nor on the publishing or subscribing processes.

What We Will Cover What is a CAR and how is it installed? What is the Development Impact? How do you build them? What is a Deployment Descriptor? Converting Classifieds Questions? u

Non-CAR Images Approach uPortal Root Directory Tight Coupling Installation Dependant Stylesheet WEB-INF classes media <xsl:variable name="mediaPath">media/org/jasig/portal/channels/Cbookmarks</xsl:variable> …/...gif … stylesheets <img src="{$mediaPath}/folder_delete.gif“…

CAR Images Approach ChannelRuntimeData.java: getBaseMediaURL( Object aChannelObject ) getBaseMediaURL( Class aChannelClass ) getBaseMediaURL( String resourcePath ) Channel object or class loaded from CAR Path of resource internal to CAR Returns: • “media/” if not deployed as a CAR • Base URL for extracting resource from CAR. Resource path internal to jar should be appended. Note: only supports gif, jpeg, jpg, jpe in 2.1.x.

CAR Images Approach(Channel Java Source) if ( mediaBase == null ) { mediaBase = runtimeData.getBaseMediaURL( this ); String cls = getClass().getName(); String pkg = cls.substring( 0, cls.lastIndexOf( '.' ) ); mediaBase = mediaBase + pkg.replace( '.', '/' ) + '/'; } // ie: mediaBase = base + com/sct/pipeline/uportal/channels/carlot/ … XSLT xslt = new XSLT (this); xslt.setStylesheetParameter( "mediaPath", mediaBase );

Stylesheet <xsl:stylesheet version="1.0“ …> <xsl:param name="mediaPath"></xsl:param> … <img src="{$mediaPath}/car.jpg“… CAR Images Approach(Channel Stylesheet)

Media Base URL = “tag.idempotent.worker.carRsrc.target.n43.uP?carRsrc=“ Car Images Approach(Carlot Channel)

Java Source Code Stylesheet <xsl:stylesheet version="1.0“ …> <xsl:param name="mediaPath"></xsl:param> … <img src="{$mediaPath}/car.jpg“… CAR Images Approach Lighter Coupling Internal To CAR Installation Independant

Stylesheet List Aspects Carlot’s channel.ssl stylesheet list file. <?xml version="1.0"?> <?xml-stylesheet title="CarListStyleSheet" href="stylesheets/channel.xsl“ …> <?xml-stylesheet title="CarListStyleSheet" href="com/sct/pipeline/uportal/channels/carlot/stylesheets/channel.xsl" …> Note: Use fully qualified jar file resource paths or be certain that the path used is relative to calling document.

Stylesheet Aspects Include, Import, and document follow similar guideline. <xsl:variable name="palette" select="document('v2colors.xml')/*/color"/> <xsl:import href="bookmark_tree_html.xsl" /> <xsl:include href=“com/sct/uportal/channels/accnt/edits.xsl" />

How Do You Build Them? Short Answer: jar cf fileName.car… Long Answer: Dependant on internal development policy. Use a tool.

JA-SIG’s portal-channels • Uses top level directory for each channel. • Includes appropriate elements in directory structures mimicking uPortal deployment directory structures. • Uses package relative directory structures beneath mimicked deployment directories. • Provides build and deployment tool with channel.

Intermediate org jasig portal channels bookmarks *.java, *.ssl, *.gif, *.xsl, etc. Portal-channels CAR Building ANT portal-channels Bookmarks build.xml build.properties bookmarks.car properties source webpages media stylesheets Package relative sub-directories UBC_Webmail

SCT’s CDK Policy 1) Use package-relative development directory structure. 2) Use directory naming scheme to differentiate channel base directories. 3) Provide build/deployment tool separate from channels.

CDK’s Directory Structure channels project com Institution sct Division pipeline uportal Build tool used portion channels carlot banner Channel Base Directories email myaccount edu

CDK is Ant Based ant list [listFiles] --- Channels in development: [listFiles] com/campuspipeline/uportal/channels/cpAttributes [listFiles] com/sct/pipeline/uportal/channels/carlot [listFiles] edu/wasatch/college/uportal/channels/example1 [listFiles] com/sct/uportal/channels/banner Also shows channels deployed as CARs, channels with web-visible or class resources (traditional deployment), and configuration information

CDK’s Directory Structure ANT channels project com Intermediate sct com pipeline sct uportal pipeline channels carlot.car uportal carlot channels banner carlot email *.java, *.ssl, myaccount *.gif, *.xsl, etc. edu

SCT’s Ant Based CDK Tool ant car car: [selectFile] Select the channel directory to be archived: [selectFile] (0 com/campuspipeline/uportal/channels/cpAttributes, [selectFile] 1 com/sct/pipeline/uportal/channels/carlot, [selectFile] 2 edu/wasatch/college/uportal/channels/example1, [selectFile] 3 com/sct/uportal/channels/banner) 1 [mkdir] Created dir: /cdk/tmp/com/sct/pipeline/uportal/channels/carlot [javac] Compiling 1 source file to /opt/cp/sdk/ui-sdk/cdk/build [jar] Building jar: /cdk/tmp/carlot.car [move] Moving 1 files to /opt/pipeline/webapps/luminis/WEB-INF/cars [delete] Deleting directory /cdk/tmp

Best Practices • Always use globally unique, package relative directories as specified in Java Language Specification, section 7.7. • Com.sct…., org.jasig…., edu…. • Develop an internal policy on channel development practices. • Provide a tool to make life easier for developers thereby encouraging adherence to the policy. • Use deployment descriptors.

What is a Descriptor? • A deployment descriptor is: • located in CAR’s /META-INF/comp.xml • Answers the question, “What’s in it for me?” • Services • Workers • Extensions • Channels • Table Creation & Population • Is processed each time server starts up.

What is a Descriptor? Newest version of Luminis CDK looks for META-INF directory in channel base directories and promotes it and its contents to the root of the CAR during construction. Non-Luminis CDK developers: define policy of where to locate then use build tool to promote to top level of CAR.

CDK’s Directory Structure channels project com Institution sct Division pipeline uportal Build tool used portion channels carlot banner Channel Base Directories email myaccount edu

CDK’s Directory Structure channels project com META-INF in channel base directory gets promoted to root of CAR sct pipeline uportal channels carlot META-INF comp.xml edu

Location in CAR jar tf carlot.car META-INF/ META-INF/MANIFEST.MF META-INF/comp.xml <Other Directories> com/sct/pipeline/uportal/channels/carlot/car.jpg com/sct/pipeline/uportal/channels/carlot/Channel.class …

Descriptor Tags <?xml version=“1.0”?> <component> LuminisUportal <service> 3.1 2.2 <worker> 3.1 2.2 <ext> 3.1 2.2 <channel-definition> 3.2 2.3.x? <database> coming soon 3.3? 2.3.x? </component> Note: There is no limit on the total number of each tag.

Descriptor Tags Service Tag Conforms to structure used for services.xml. <service> <name>CMS XML Service</name> <class>com.sct.cms….XMLService</class> <jndi_name>com.sct.cms…XMLService</jndi_name> <method>startup</method> <arguments> <argitem> <datatype array="true">java.lang.String</datatype> <value>60</value> </argitem> </arguments> </service>

Descriptor Tags Worker Tag has single attribute: class <workerclass="com.sct.cms…ChanPubWorker"/> Class implements IWorkerRequestProcessor. Worker “name”: ‘_’ replacing ‘.’ in class name. ChannelRuntimeData.getBaseWorkerURL( “com_sct_cms…ChanPubWorker”)

Descriptor Tags Extension Tag has single attribute contentHandler <ext contentHandler=“aContentHandlerClass”>??? </ext> Contents defined by provided content handler. Handler receives calls for: documentStart() Content generated event calls…. documentEnd()

Descriptor Tags <ext contentHandler="com…SecureURLMapHandler"> <DEFINITION rootAt="cp"> <NODE name="worker.com_sct_cms…ChanPubWorker.uP"> <LABEL name="secure"> true </LABEL> <LABEL name="auth-method"> BASIC </LABEL> <LABEL name="acl:any"> role:admin </LABEL> </NODE> </DEFINITION> </ext>

Descriptor Tags Channel Definition tag enables auto-publishing of channels from CARs. Will not install if functional name already in use. Conforms generally to chanPub tool DTD. Groups ignored. Access granted only to admins. Categories ignored. Auto-created “Auto-Published” category used. Administrators can review channel or grant access to reviewing group for approval before opening access to others.

Descriptor Tags <channel-definition><title>Carlot2.5</title><name>Carlot2.5</name> <fname>carlot2.5</fname><desc>Installed Car Viewer</desc><type>Custom</type><class>com.sct.pipeline.uportal…carlot.Channel</class><timeout>5000</timeout><hasedit>N</hasedit><hashelp>N</hashelp><hasabout>N</hasabout><secure>N</secure><locale>en_US</locale><makeFNameAccessibleOnly/> <channel-definition>

Descriptor Tags New Database tag enables automatic processing of declared and included tables.xml and data.xml files. Path to files must be relative to base of CAR. <database> <tables>edu/iastate/ait/channels/classifieds/tables.xml</tables> <data>edu/iastate/ait/channels/classifieds/data.xml</data> </database>

Converting Classifieds 1) Converted its build tool to work in my environment. (See jasig email 3/10/2004) 2) Compiled into its build directory and used as base directory for creating the CAR. 3) Moved images directory into channel’s directory. 4) Modified channel code to call getBaseMediaURL() and pass value to stylesheets. 5) Noticed that it includes its own incompatible version of BrowserInfo.java. (Removed dependancy for now.) 6) Loaded the database using its build tool. 7) Added deployment descriptor to auto-publish. 8) Jar’d and Moved classifieds.car into target directory. 9) Bounced the webserver.

Keep in mind… 1) Use jar tool or carlot channel to verify CARs contents are what you think they are. 2) If images are broken highlight image, select properties, and see what URL is being generated. 3) Make sure the class in your CAR is really being used.

Questions? Mark Boyd mboyd@sungardsct.com

Becoming a Channel Archive Master, It’s as easy as ‘abc’