The Salmon Open Framework

for Internet Applications (SOFIA)

Version 2.3 Manual Installation Guide

Salmon LLC
220 Old Country Road
Mineola, NY 11501-4271
(516) 742-7888

Version 2.3
SOFIA 2.3 Manual Installation Guide

Copyright Notice

Licensed Material - Property of Salmon LLC

(C) Copyright Salmon LLC. 1999 – 2004

The Salmon Open Framework for Internet Applications (SOFIA) has been released under
dual licensing schemes. Unregistered versions of SOFIA fall under the GNU General
Public License. This in effect means that non-internal projects that you create with SOFIA
will also have to be released under the GNU GPL as open source. Once you register for
SOFIA, you will be able to use it under the Salmon license as well. The Salmon license
allows you to distribute SOFIA binaries with your SOFIA application without having to
make your software open source. Registration is free. To register your copy of SOFIA,
please visit http://www.salmonllc.com/register.

This program is free software; you can redistribute it and/or modify it under the terms of
the GNU General Public License version 2 as published by the Free Software
Foundation; Registered versions can be distributed under the terms of the Salmon
Software License version 1 as well;

This program is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
details.

To get a copy of the GNU GPL, write to the Free Software Foundation, Inc., 59 Temple
Place - Suite 330, Boston, MA 02111-1307, USA.

To view the full GNU GPL and Salmon Software License on-line please visit
http://www.salmonllc.com/license.

This product includes software developed by the Apache Software Foundation

(http://www.apache.org/).

Page 2 of 11 Copyright 1999-2004 Salmon LLC

SOFIA 2.3 Manual Installation Guide

Before you start

For MS-Windows users SOFIA provides an automatic install program as a separate

download (SOFIAInstallation2-3.zip). This package however, contains a distribution that
must be installed manually by following the steps provided in this document. Is intended
for developers who cannot use the automatic procedure because they don’t have MS-
Windows, are having trouble with the automated install, or only want a subset of the full
SOFIA install. The manual install procedure is not supported by Salmon, although you
may be able to get help with problems from the open source community on the SOFIA
SourceForge forum at http://sourceforge.net/forum/forum.php?forum_id=180505.

The Salmon Open Framework for Internet Application (SOFIA) integrates best of breed
products from several different sources. This install procedure has been tested for
development with:

• JDK 1.4
• Tomcat 4.1.24/Tomcat 5.0.27
• MySQL 3.23 and 4.0
• Eclipse version 21 or 3.0.
• Dreamweaver MX 6 or Dreamweaver MX 7 (2004).

We recommend at least 256mb of memory to be able to run all these different tools
simultaneously, but 512mb will provide a better experience. In addition, you will need at
least 80 mb of free disk space.

SOFIA applications can be deployed on any J2EE compliant servlet/JSP engine. SOFIA
applications have been successfully deployed on various versions of Tomcat, Bea
Weblogic, IBM Websphere, Caucho Resin, Orion and SilverStream in MS-Windows,
Linux, Solaris and VMS environments. SOFIA applications can be also be deployed
with most of the popular commercial and open source database engines including
MySQL, Sybase, Oracle, MS SQL Server, DB2, Ingres, Postgres and Firebird.

These instructions will step you through the process of manually installing a binary
version of SOFIA and the SOFIA example application using Tomcat 4.1 or 5.0 and
MySQL Version 3 or 4.

In addition if you want to manually install SOFIA for development, instructions are
provided for Eclipse 2.1 and 3.0 and Dreamweaver MX or MX 2004.

Note on directories described in this document

This document will reference several directories that you will create:

/SOFIA = the SOFIA home directory on your file system.

/TOMCATDIR = the home directory where Tomcat was installed

/ECLIPSEDIR = the home directory where Eclipse was installed

Note: The SOFIA directory with source code and resources should be installed
locally on the machine you will use for SOFIA development or on a drive that is
always accessible to that machine.

Page 3 of 11 Copyright 1999-2004 Salmon LLC

SOFIA 2.3 Manual Installation Guide

Upgrading an old manual install

If you have used the SOFIA Manual Install procedure for SOFIA 2.2, please note
that SOFIA 2.3 now supports property files in the /WEB-INF/properties folder of
each individual web application or a shared property file location. SOFIA 2.2 only
supported the shared location. Because installation is easier with the property
files in the WEB application, this distribution now uses that method. So if you are
installing this package over a previous manual install, you should make the
following changes to your Tomcat configuration, before doing this install:

1) Start Tomcat without the switch –Dsalmon.props.path in the command line.

Depending on how you have installed Tomcat, this may mean changing the
CATALINA_OPTS environment variable, editing the catalina.sh or catalina.bat file
in /Tomcat/bin or changing the MS Windows shortcut used to launch tomcat.
2) Remove the directory /Tomcat/salmonprops. If you have existing SOFIA
applications on the server other then sofiaExamples and don’t want to lose the
property files for them, first create a properties folder under the /WEB-INF folder of
each of your SOFIA applications and copy the property files appropriate to each
application to that folder. Note: you should copy the SOFIA System.properties file to
each /WEB-INF/properties folder.
3) Remove the old salmon.jar from /Tomcat/common/lib. If you have existing SOFIA
applications on the server, create a lib folder under the /WEB-INF folder of each
and copy in the new salmon.jar from this distribution into it (the new salmon.jar will
be in /Sofia/WebApp/sofiaExamples/WEB-INF/lib).

Page 4 of 11 Copyright 1999-2004 Salmon LLC

SOFIA 2.3 Manual Installation Guide

Manually Installing SOFIA and SOFIA example application on Tomcat.

These steps assume that you have already unpacked the SOFIA distribution to your
local file system and now have the following directory structure.

/SOFIA/Resources :Various resources such as jar files or plug-ins

/SOFIA/SourceCode : Source Code for SOFIA and the Example app
/SOFIA/WebApp :SOFIA Examples in a web app (exploded war) format

Step 1: Install Java

Install the Java Development Kit version 1.4.1. This can be downloaded from
Sun’s web site at http://java.sun.com/j2se/1.4/download.html . Make sure to
download the full SDK (System Development Kit) and not just the JRE (Java
Runtime Environment). Run the downloaded exe and follow instructions on
screen. If you already have JDK 1.4.x installed on your system you may skip this
step.

Step 2: Install Tomcat 4.1 or 5.0

Install Tomcat 4.1 or 5.0. This can be downloaded from

http://jakarta.apache.org/site/binindex.cgi. Follow the instructions in the download
to install Tomcat. Make sure you use the default Tomcat port of 8080 in your
installation. If you already have Tomcat 4.1 or 5.0 on your system on port 8080
you can skip this step.

Step 3: Install MySQL:

Install the MySQL database engine version 3.23 or 4.0. MySQL can be
downloaded from http://www.mysql.com/downloads/index.html. If you already
have MySQL 3.23 or 4.0 on your system you can skip this step. Note:
instructions later in this document will refer to setting up the SOFIA example
database in a MySQL installation, although SOFIA can be used with almost all of
the major database engines. You may be able to substitute some of the steps
described below with analogous ones for the engine you are using.

Page 5 of 11 Copyright 1999-2004 Salmon LLC

SOFIA 2.3 Manual Installation Guide

Step 4: Install the SOFIA Examples Database

The database installation script below uses ANSI SQL DDL to create the tables
and data for the SOFIA examples database. You may be able to use it in engines
other then MySQL either unchanged or with minor changes.

1) Start the MySQL daemon: From a command prompt go to the /MySql/bin

directory and run mysqld-max --standalone (two dashes before
standalone). In Linux systems, you may start MySql with the command:
./mysqld_safe --user=mysql &.
2) From a second command prompt, run the MySql command processor. Go to
the /MySql/bin directory and run: mysql --user=root
(on Linux: ./mysql --user=root).
3) If this in an upgrate drop the old sofia database
At the mysql> prompt type: drop database sofia and press enter.
4) At the mysql> prompt type: create database sofia; and press enter.
5) At the mysql> prompt type: use sofia; and press enter.
6) At the mysql> prompt type:
source /Sofia/Resources/mysql/create_sofia_db_with_data.sql and press
enter. Note: Sofia is the location on your file system where you unpacked the
SOFIA distribution including drive letter if necessary.
7) At the mysql> prompt type: quit and press enter. This will exit the mysql
command processor. Leave the database daemon running at the other
command prompt.

Step 5: Install the SOFIA Example Application on Tomcat

1) From /SOFIA/Resources/lib directory copy the jars mm.mysql-2.0.11-

bin.jar (MySQL JDBC driver) and portlet-api-1.0.jar (Portlet API) to the
/TOMCATDIR/common/lib directory. If you have installed the SOFIA
database on a different database engine, copy the jar files for the JDBC
driver for that engine instead of the MySql jar file. Also copy the JDK jars
activation.jar and mail.jar if they aren’t already in the
/TOMCATDIR/common/lib directory.
2) Copy the directory sofiaExamples from /SOFIA/WebApp to the
/TOMCATDIR/webapps directory.
3) If you have installed MySql with different setting then the default or are using
a different database engine, modify the database connection parameters at
the bottom of the System.properties file to match your setup. With a text
editor, edit the file System.properties in the
/TOMCATDIR/wepapps/sofiaExamples/WEB-INF/properties

Step 6: Launch Tomcat

Launch Tomcat using the MS-Windows short cut, startup.bat (MS-Windows) or

startup.sh (Linux) file in the /TOMCATDIR/bin directory.

Step 7: Launch your browser

Point your browser to http://localhost:8080/sofiaExamples/Jsp/HomePage.jsp to

run the example application. In the example application you can see code
examples, and the full SOFIA documentation. In order to go through the tutorial,
you will need to install Eclipse and Dreamweaver support described below.

Page 6 of 11 Copyright 1999-2004 Salmon LLC

SOFIA 2.3 Manual Installation Guide

Setting up a SOFIA development environment

Before you can complete this process you must first manually install SOFIA and the
SOFIA example application as outlined on the previous pages.

Manually Installing the Dreamweaver plug-in

Note: SOFIA Uses Dreamweaver as a GUI development environment for editing JSP
pages. You can also use a regular text editor to edit your JSP files. If you would rather
not use Dreamweaver or Dreamweaver is not available on your platform you can skip this
part of the install.

Step 1: Install Dreamweaver

Install Dreamweaver MX or MX 2004 on your workstation. Dreamweaver MX

provides a GUI development environment for creating your JSPs. You can
download Dreamweaver MX 2004 from:
http://www.macromedia.com/cfusion/tdrc/index.cfm#loc=en_us&view=snTDRC&v
iewName=Downloads. After installation, launch Dreamweaver once to complete
the install and then exit.

Note: Dreamweaver is only available on MS Windows and Macintosh platforms.

To run Dreamweaver on Linux, you can use the Linux Windows emulation
product Crossover Office (http://www.codeweavers.com), but at the time of this
writing Crossover Office only supported Dreamweaver MX (not 2004) and only at
the bronze level. Bronze level means that the software still has significant bugs
when running under Linux and so might be suitable for a production environment.

Step 2: Install the SOFIA Dreamweaver plug-in

Run the Macromedia Extension Manager. Click on “Install New Extension” and
install the extension:

/SOFIA/Resources/Dreamweaver/Mxp/SofiaExtensionsMX.mxp

Follow the instructions on screen and answer Yes if the extension manager asks
you if you want to replace any files. Make sure to close Dreamweaver and the
extension manager before going on to the next step.

Page 7 of 11 Copyright 1999-2004 Salmon LLC

SOFIA 2.3 Manual Installation Guide

Manually Installing the SOFIA Eclipse plug-in

Before you can complete this process you must first manually install SOFIA and the
SOFIA example application as outlined on the previous pages. Also if you are using
Dreamweaver, the Dreamweaver install should be completed prior to this step.

Step 1: Download and Install Eclipse 2.1, or 3.0

You can download Eclipse at http://www.eclipse.org/downloads/index.php.

Follow the instructions to install Eclipse. To work with SOFIA, Eclipse must be
used with JDK version 1.4 or above. Note: Eclipse must use a Java Development
Kit 1.4 or better and not just a Java Run Time Environment. The JDK used by
Eclipse can be set by clicking on the menu Window->Preferences->Java-
>Installed JREs.

Step 2: Put the SOFIA DLLS on your System path (MS-Windows Only)

SOFIA comes with two DLLs that are used only for MS-Windows installations.
These are located in the directory /SOFIA/Resources/DLLS. Both these DLLs
are optional. One is SDCLIENT.DLL which allows SOFIA to interface with a
SecureID server (a service which provides electronic key chains that produce
passwords that are only valid for a short time). The SOFIA secure id package
works through JNI calls to this DLL and so only works on MS-Windows
environments. The other is REGUPDATE.DLL, which is used to access the MS-
Windows registry when a new SOFIA project is created in an IDE. The SOFIA
plug-in uses this DLL to create new registry entries to set up a site definition in
Dreamweaver that corresponds to the new SOFIA Java project in the IDE.
Without this DLL installed you will have to manually create the Dreamweaver site
definition whenever you create a new SOFIA project.

On MS-Window, copy the DLLs to a directory in your system path like the
C:\WinNT\System32 directory. Otherwise you can skip this step.

Step 3: Copy the plug in to Eclipse

Copy the directory com.salmonllc.eclipse from /SOFIA/Resources/Eclipse to

/ECLIPSEDIR/plugins.

Step 4: Stop Tomcat

If Tomcat is running, shut it down. You will launch it later from within the IDE.

Page 8 of 11 Copyright 1999-2004 Salmon LLC

SOFIA 2.3 Manual Installation Guide

Step 5: Edit the System.properties file

Edit the file System.properties in the directory

/TOMCATDIR/webapps/sofiaExamples/WEB-INF/properties directory and
manually specify the correct paths for the following properties (near the end of
the file). Note on MS-Windows systems include a drive letter and use \\ as the
path separator. You may set these paths manually now or later in the Eclipse IDE
via the SOFIA properties dialog once the plug-in is installed
a) IDEDreamweaverPath:The path to the Dreamweaver Executable
program.
b) There are several IDEBrowserPath properties:
IDEBrowserPath: The path to the executable for the default
browser
IDEBrowserPath.IE: The path to Internet Explorer
IDEBrowserPath.Netscape: The path to Netscape
If you want to be able to launch browsers other then IE or Netscape
from the Eclipse plug-in, you can add additional
IDEBrowserPath.BrowserName properties (BrowserName can’t
contain spaces). If you don’t want Netscape or IE as options, you
may remove those properties.

Step 6: Start Eclipse and Set Up the Environment

a) Activate the SOFIA Menu and Toolbar by going to Window ->

Customize Perspective and check the “Salmon Menu” from the
“Other” folder. You should repeat this step for each perspective that
you want to be able to run SOFIA applications from. The common
perspectives used in SOFIA development are Resource, Java and
Debug perspectives.
b) Click File->New Project and select “Install/Upgrade Sofia
Framework” from the Java menu and follow the instructions on the
wizard. Specify the following properties on the second screen of the
Wizard:
SOFIA Install Directory: /SOFIA
Tomcat Install directory: /TOMCATDIR
JDBC Driver Jar File: /TOMCATDIR/common/lib/mm.mysql-
2.0.11-bin.jar
c) Click File->New Project and select “Install/Upgrade Sofia Example
Application” from the Java menu and follow the instructions on the
wizard. Specify the following properties on the second screen of the
Wizard:
SOFIA Install Directory: /SOFIA
Tomcat Install directory: /TOMCATDIR

Step 7: Complete the Browser/Dreamweaver path set up

If you already set up the paths for your browsers and Dreamweaver in step 5 you
can skip this step. Otherwise, on the Eclipse menu bar click SOFIA->Set
Properties. At the bottom of the dialog are edit fields where you can specify the
paths to Dreamweaver and to various browsers.

Page 9 of 11 Copyright 1999-2004 Salmon LLC

SOFIA 2.3 Manual Installation Guide

Step 8: Launch the sofiaExamplesEclipse application

From the Eclipse toolbar, run the SOFIA Example application by clicking the
down arrow next to the “Run default page in browser” tool bar button and
choosing the browser to run the page in.

Step 9: Verify the Dreamweaver installation

If you are using Dreamweaver, launch it by clicking on the toolbar button. If
Dreamweaver doesn’t launch, check the Dreamweaver path in under SOFIA>Set
Properties.

Verify that the Site for SOFIAExamplesEclipse was set up properly. You can see
this by clicking on Site->Edit Sites or Site->Manage Site on the Dreamweaver
menu. If you see a site list with sofiaExamplesEclipse, then the site was created
properly and you are ready to go. Otherwise create a new site with the following
properties:

Use the basic tab of the site definition wizard: When prompted, specify the
following:

Name: sofiaExamplesEclipse
Use a server Technology: Yes
Server Technology: JSP
Editing Files: Edit and Test Locally
File Location: /ECLIPSEDIR/workspace/sofiaExamplesEclipse
Root URL: http://localhost:8080/sofiaExamplesEclipse/

Once you’ve created the site, click on the menu Commands->Salmon Set
Properties and specify the following properties for the site.

Prefix: salmon:
Application: sofiaExamplesEclipse
Tag Lib: taglib.tld
Servlet URL: http://localhost:8080/sofiaExamplesEclipse
Translator Mode: On
Default Language: en

Note: If using Dreamweaver with Cross Over Office on Linux, using the IP
address of the local workstation instead of localhost may result in better
performance.
Once your site is properly set up, you can verify that everything is working
properly by open the SOFIAExamples home page (/JSP/HomePage.jsp). You
should see a rendering of the page in the design area. Clicking on the globe to
run it should pop up a browser window with the page.

Page 10 of 11 Copyright 1999-2004 Salmon LLC

SOFIA 2.3 Manual Installation Guide

Using JDK 1.3 instead of JDK 1.4

If you wish to use JDK 1.3 instead of JDK 1.4, you may do so by following the steps
below. Note: The SOFIA Swing components and IDE Tools require JDK 1.4. JDK 1.3
can only be used for server deployed applications.

1) Make sure you have both JDK 1.3 and 1.4 configured in Eclipse, with 1.3 as the
default. JDK 1.3 will be used for running Tomcat and your application and JDK 1.4 will
be used for the SOFIA IDE Tools, which use SOFIA Swing components and require
1.4. In the Eclipse workspace, select Window->Preferences->Java->Installed JRE’s.
Make sure you have a JDK 1.3.x and 1.4.x in the list with 1.3 selected as the default.

2) Once you do this, some of the Salmon Open Framework project won’t compile. Right
click on the Salmon Open Framework project->Java Build Path->Libraries and add the
following external jars to the build path (Jars can be found in /Tomcat 4.1/common/lib)
crimson.jar
xalan.jar
jdbc2_0stdext.jar
Once you have set the build path, most of the framework will now compile properly.
Some of the classes in the com.salmonllc.util.swing package won’t compile property,
but you should still leave those classes as is in the workspace.

3) Add the following properties to your System.properties file in /Salmon Open

Framework/properties. This will tell the Salmon Eclipse plug-in to run IDE Tools other
then Tomcat launching in JDK 1.4 instead of the default 1.3:

IDEEclipseVM=Name of the JDK 1.4 JVM you set up in step 1

IDEEclipsePlugInJar=ECLIPSEDIR\\plugins\\com.salmonllc.eclipse\\
salmonEclipse.jar

4) Change the SOFIA runtime class path to include the tools.jar from the new JDK.
From the Eclipse Workbench select SOFIA->Set Properties and change the tools.jar in
the server class path to /JDKDIR/lib/tools.jar.

Page 11 of 11 Copyright 1999-2004 Salmon LLC