How to build and configure a scam Portfolio system

We will briefly go through how to:

get the latest SCAM portfolio from cvs
configure and build SCAM portfolio
install and configure jboss
deploy the SCAM portfolio
tailor SCAM portfolios with the help of SHAME

Getting the code for SCAM

To check out from cvs you have to follow the instructions on sourceforge on how to check out modules, see http://sourceforge.net/cvs/?group_id=45552 and/or read on below.
The modules that should be checked out are:

scam_libs – all external librarys that the portfolio depends on.
scamDrutten – utility and complementary code to the jena RDF API.
scamRepository – API that is responsible for the storage of RDF.
scamController – this is the controller framework for building.
scamTaglib – common taglibs used by e.g. the scamPortfolio.
scamPortfolio – the portfolio application

To build the scam portfolio all modules should be checked out. Either check out one at a time or use the equivalent all alias instead. If you do it by hand be careful to name the directories as the module names (on unix systems the directory names are case sensitive), otherwise the build process will fail.

From the commandline type:
cvs -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/scam login
and press return when prompted for a password, then type:
cvs -z3 -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/scam co all
and wait for the checkout to complete.

Configuring and building SCAM portfolios

For every checked out module there is an ant build script called build.xml in the build subdirectory. For instance, building the scamRepository is done by going down to the build directory and typing (make sure that you have the JAVA_HOME environmental variable is set correctly first):

ant dist

Since scamRepository depends on scamDrutten scamDrutten will be built first, there might be some warnings, but it should compile and leave you with some jar-files in the lib directory.

Now, lets build the scamPortfolio. First go to the scamPortfolio's build directory. Before you start building we should do some configuration. There is a file called build.properties.sample, copy it to build.properties and look at the comments within. Lets focus on some of the most cruical properties that you should configure. Observe that there is reasonable default in most cases, so if you want to change something you often need to uncomment a property and then set the value to something new.

For faster builds just uncomment skip.javadoc= and skip.extdoc=.
Set ui.language.default to your preferred language, currently only english, german or swedish is supported (en, de and sv). (To support a new language with language code xx create the messages_xx.properties file in the conf directory.)
Set the scam.repository.content.base, scam.repository.temp.content.base and scam.repository.backup.base properties to sensible values. That is, the directories you specify should be on the machine where you plan to deploy the portfolio system, e.g. on a unix system it is typically three catalouges in /var or in /home/scam.
Set the property scam.uri.namespace to some namespace that you consider your own, e.g. one one installation we have used scam.uri.namespace=knowgate.nada.kth.se. Observe that this namespace is used for generating globally unique identifiers so if it is not set to something unique, the identifiers generated in the system will fail to be unique. (This property is not commented out in the property file so you have to add it yourself.)

Now you can start the build process by typing:

ant cleanAll

ant dist

in the build directory. The cleanAll is just to make sure no old configurations are preserved by mistake in the jar files. The result will be the file scamPortfolio.ear file in the lib/server directory.

Downloading, installing and configuring jboss

For compatability reasons we suggest that you install the jboss-3.2.1 bundled with tomcat-4.1.24. Since this version no longer is available at jboss.org you can download it from one of our servers at:

http://knowware.nada.kth.se/~matthias/jboss.tgz

Unzip this into some suitable directory, on unix systems /usr/local is often used. Go to the bin directory in the jboss installation and change the run.conf file as following:

Set the JAVA_HOME to where there is a j2sdk1.4 or later.
Change the maximum memory usage of java by uncommenting the JAVA_OPTS and make sure the flag -Xmx is set to something bigger than 250 Megabytes.
E.g. JAVA_OPTS="-server -Xmx512m".

To start jboss, go to the bin directory and use the apropriate run-script for your operating system.

Deploying the SCAM portfolio

Just copy the scamPortfolio.ear produced above to the server/default/deploy directory in the jboss installation and it will be deployed automatically.

You can check that it worked by directing a browser to:

http://localhost:8080/portfolio/main

(Where you have to give the appropriate name of the machine you installed on instead of localhost if you installed elsewhere.)

Using SHAME to fill your SCAM

Now when you have your portfolio system running you probably want to customize what kind of resources and what metadata forms it should provide to the end users. The types and accompanied forms provided by default are the Dublin Core Metadata Initiative Types (plus some extra types we missed badly, such as Person).

In short there is a file datatypes.rdf in the conf directory (in scamPortfolio) that controlls available types (modeled as rdf classes), how they are related (with subclass relations) and what formlets they trigger. Formlets are SHAME-configurations that describe form-snippets and how they relate to specific RDF constructs. When a resource is edited or presented it is done through a form that is generated from the union of all relevant formlets for it. Relevant formlets is simply those the resource's type(s) specify (including supertypes).

Observe that:

The SHAME formlets are referred via their URIs. You have to make sure that all formlets that you want to use are loaded in advance. You do not load single formlets but entire formlet-sets by specifying the RDF files where the formlet-sets are defined. Those formlet-set RDF files are specified in the build.properties file by the scam.formlets.file property. Se the commented example in the build.properties.sample file.
The SHAME formlets are actually not referred by the types directly, instead they are referred through an intermediate resource where a priority is specified. The priority is used for sorting the formlets before they are compiled into one big form.
There is sometimes jsp-pages pointed to via the static-view and tile properties (on the types and on the intermediate formlet resources respectively). These jsp-pages are sometimes used instead of the formlets, but only for presentation (e.g. resources of type calender are not suitable to present in a form).
It is possible to define new kinds of folders by subclassing the Collection class. Furthermore, for a specific folder type it is possible to controll which type of resources it is allowed to contain via the containsPartsOfClass property.