SellWin Installation Instructions (v 1.0.5)


August 27, 2002

Contents



Client Installation



Basic Software Requirements

Regardless of the type of operating system you will be running SellWin's client on, you will
need the following products installed for the client to operate:

  1. MYSQL database
  2. Java JDK SE 1.4
  3. MYSQL "MM" JDBC driver
The installation steps of these add-on products is different for Windows and UNIX.


Windows 98 Client Install



Download the SellWin Client Bundle

Installing the MYSQL database


Configure MYSQL

Installing the JDK

Starting the SellWin Client

To run SellWin manually:
For developers, you can start the SellWin GUI by running the following command from the SellWin home directory:


Linux Client Install (Coming soon!!)



Installing the MYSQL database

Configure MYSQL

Installing the JDK

Installing the SellWin Client JAR

Installing the MYSQL JDBC Driver

Starting the SellWin Client

You will need to specify all the JBoss client JAR files in your CLASSPATH when running the GUI manually:

export JBOSS_HOME=/apps/jboss-3.0.0_tomcat-4.0.3
CLASSPATH=$CLASSPATH:$JBOSS_HOME/client/concurrent.jar
CLASSPATH=$CLASSPATH:$JBOSS_HOME/client/gnu-regexp.jar
CLASSPATH=$CLASSPATH:$JBOSS_HOME/client/jaas.jar
CLASSPATH=$CLASSPATH:$JBOSS_HOME/client/jacorb.jar
CLASSPATH=$CLASSPATH:$JBOSS_HOME/client/jboss-client.jar
CLASSPATH=$CLASSPATH:$JBOSS_HOME/client/jboss-common-client.jar
CLASSPATH=$CLASSPATH:$JBOSS_HOME/client/jbossha-client.jar
CLASSPATH=$CLASSPATH:$JBOSS_HOME/client/jboss-iiop-client.jar
CLASSPATH=$CLASSPATH:$JBOSS_HOME/client/jboss-j2ee.jar
CLASSPATH=$CLASSPATH:$JBOSS_HOME/client/jboss-jsr77.jar
CLASSPATH=$CLASSPATH:$JBOSS_HOME/client/jbossmq-client.jar
CLASSPATH=$CLASSPATH:$JBOSS_HOME/client/jbossmqha.jar
CLASSPATH=$CLASSPATH:$JBOSS_HOME/client/jboss-net-client.jar
CLASSPATH=$CLASSPATH:$JBOSS_HOME/client/jbosssx-client.jar
CLASSPATH=$CLASSPATH:$JBOSS_HOME/client/jboss-system-client.jar
CLASSPATH=$CLASSPATH:$JBOSS_HOME/client/jcert.jar
CLASSPATH=$CLASSPATH:$JBOSS_HOME/client/jmx-connector-client-factory.jar
CLASSPATH=$CLASSPATH:$JBOSS_HOME/client/jmx-ejb-connector-client.jar
CLASSPATH=$CLASSPATH:$JBOSS_HOME/client/jmx-rmi-connector-client.jar
CLASSPATH=$CLASSPATH:$JBOSS_HOME/client/jnet.jar
CLASSPATH=$CLASSPATH:$JBOSS_HOME/client/jmx-rmi-connector-client.jar
CLASSPATH=$CLASSPATH:$JBOSS_HOME/client/jnet.jar
CLASSPATH=$CLASSPATH:$JBOSS_HOME/client/jnp-client.jar
CLASSPATH=$CLASSPATH:$JBOSS_HOME/client/jsse.jar
CLASSPATH=$CLASSPATH:$JBOSS_HOME/client/log4j.jar


From the command line you can type:

/home/jmccormi % java sellwin.gui.Main


You can also start SellWin using the ANT build script (build.xml) as follows:

/home/jmccormi/sellwincrm % ant run-gui


Linux Server Installation


Install the SellWin Source 

Download or copy the source JAR file into your home directory and extract the source code.   This
will be the directory used to build the server components.

Example:

cd /home/jmccormi
jar xvf sellwin.jar

This will extract the source code into a directory called /home/jmccormi/sellwin.

Basic Server Software Requirements

Regardless of the type of operating system you will be running SellWin's server on, you will
need the following products installed for building and running the SellWin server:

  1. MYSQL or Oracle database
  2. Java JDK SDK 1.4
  3. MYSQL "MM" or Oracle JDBC driver
  4. Ant Java build utility
  5. Jikes Java compiler
  6. JBoss EJB server

Database and JDBC Installation

SellWin uses JDBC calls to talk to a database.  SellWin is developed using an Oracle 8i database so the examples below will
show an Oracle installation, other databases will work as well, especially MYSQL, but will require some changes to
some of the configuration parameters.

Make sure your database is installed, if not, follow your database vendors instructions.

Database Creation

As the Oracle SYS user, create a database named 'sellwin' as follows:

% sqlplus sys/yourpassword

SQL*Plus: Release 8.1.6.0.0 - Production on Wed Jul 24 12:02:18 2002

(c) Copyright 1999 Oracle Corporation.  All rights reserved.


Connected to:
Oracle8i Enterprise Edition Release 8.1.6.1.0 - Production
With the Partitioning option
JServer Release 8.1.6.0.0 - Production

SQL> create database sellwin;
SQL> quit;


For users wanting to use MYSQL as the server database, you can create the database and basic
user permissions by issuing the following command on the server:

cd ~/sellwincrm/sql/mysql
mysql --user=root mysql < buildMYSQL.sql


This will execute the MYSQL commands in the 'buildMYSQL.sql' script.  You might want to examine
the settings in this script before you execute them.

Database User Creation

Using the Oracle SQL, create a SellWin database user, giving it permissions to create the SellWin
database schema :

% sqlplus sys/yourpassword

SQL*Plus: Release 8.1.6.0.0 - Production on Wed Jul 24 12:02:18 2002

(c) Copyright 1999 Oracle Corporation.  All rights reserved.


Connected to:
Oracle8i Enterprise Edition Release 8.1.6.1.0 - Production
With the Partitioning option
JServer Release 8.1.6.0.0 - Production

SQL> create user sellwin identified by changeme;

SQL> grant public, resource to sellwin;
SQL> quit;

Schema Creation

Using the Oracle SQL utility, create the SellWin database schema and test data:

Change directory to your SellWin source code home, then change directory to the Oracle SQL subdirectory:

% cd /home/jmccormi/sellwincrm
% cd sql/ora


Create the database schema:

% sqlplus sellwin/changeme @create_schema.sql

Create some test user roles and permissions:

% sqlplus sellwin/changeme @create_roles.sql

Create some sample state tax codes:

% sqlplus sellwin/changeme @create_state_codes.sql

Create some test user data:

% sqlplus sellwin/changeme @create_test_data.sql


Create some test product data:

% sqlplus sellwin/changeme @office_products.sql


For MYSQL databases, you will issue the following commands to build the SellWin schema:

cd ~/sellwincrm/sql/mysql
create_schema.sh
load_state_tax.sh
office_products.sh
create_roles.sh
create_test_data.sh


JDBC Installation

Make sure your Oracle JDBC driver is installed and available.  On my system, it is located at:

/apps/oracle/product/8.1.7/jdbc/lib> ls
classes111.zip  classes12.zip


We use the classes12.zip version of the JDBC driver in all of our examples.  The Oracle JDBC drivers can be
downloaded at http://www.oracle.com.


Ant Installation

Download and install the Ant build utility.  Get it at:  http://jakarta.apache.org/ant/index.html.  SellWin is developed with Ant 1.5, but other versions
should work as well.  Ant is used in the SellWin build process.

After installing Ant, test it to make sure the setup is correct:

%  ant -version
Ant version 1.4.1 compiled on October 11 2001


Jikes Installation

Download and install the Jikes Java compiler.  This is only required if you want the SellWin build script to run with Jikes as the default compiler.  I highly recommend it since it makes the build go much faster.  Jikes is free as well.  Get it at:  http://oss.software.ibm.com/developerworks/opensource/jikes/
Add Jikes to your PATH, test that it is correctly set up by issuing the following command:

% jikes -version

You should see the version number printed.

Installing JBoss

JBoss is now the default EJB server for SellWin.  JBoss has several key benefits including:  open sourced, fast, easy development, and free!
SellWin is developed currently with JBoss Version 3.0.   Get it at:  http://www.jboss.org/downloads.jsp

I highly recommend you test your JBoss installation to verify that its ready for the SellWin install before proceeding.  Instructions on JBoss
installations are available at the JBoss web site.  There is a good book on JBoss from Sams Publishing, "JBoss Administration and Development",  by Scott Stark and Marc Fleury, 2002.

In my examples, I install JBoss in a directory called /apps.  My default JBoss installation is as follows:

/apps/jboss-3.0.0_tomcat-4.0.3

For this set of instructions, i've installed the Sellwin source code in the following directory:

/home/jmccormi/sellwincrm


Building SellWin


Change directory to the SellWin source home:

% cd /home/jmccormi/sellwincrm

Delete any old class files from previous builds:

% ant clean

Compile all the classes:

% ant

Build and deploy the EJB components into the JBoss deploy directory (e.g. /apps/jboss-3.0.0_tomcat-4.0.3/server/default/deploy) :

% ant deploy-ear

Configuring JBoss

JDBC Configuration


For running Oracle as the server database:

% cp /apps/oracle/product/8.1.7/jdbc/lib/classes12.zip /apps/jboss-3.0.0_tomcat-4.0.3/server/default/lib

For running MYSQL as the server database:

% cp mm.mysql-2.0.14-bin.jar /apps/jboss-3.0.0_tomcat-4.0.3/server/default/lib


Upon startup, JBoss will now be able to find the Oracle JDBC driver.

Copy the database JCA configuration files to the JBoss deploy directory:

% cd ~/sellwincrm/jboss

% cp oracle-service.xml /apps/jboss-3.0.0_tomcat-4.0.3/server/default/deploy
OR
% cp mysql-service.xml /apps/jboss-3.0.0_tomcat-4.0.3/server/default/deploy

This will define within JBoss a data source named 'SellwinDS'.

Specifying the Server Database Type


Edit the JBoss startup file, named 'run.sh' in the /apps/jboss-3.0.0_tomcat-4.0.3/bin directory.  Edit the JAVA_OPTS line to include the type of server database you will be using, by default, Oracle will be used if this property is not set:

For MYSQL:

JAVA_OPTS="$JAVA_OPTS -Dprogram.name=$PROGNAME -DDBTYPE=MYSQL"

For Oracle:

JAVA_OPTS="$JAVA_OPTS -Dprogram.name=$PROGNAME -DDBTYPE=ORACLE"

RMI Settings (JBoss 2.4 ONLY)


For JBoss 2.4.X:

Lastly, edit the jboss.properties file, change the java.rmi.server.hostname property value from localhost to the name of your
JBoss server host name.  This is required for remote SellWin clients to be able to connect to the JBoss server.  This file is located in /apps/JBoss-2.4.6_Tomcat-4.0.3/jboss/conf/default.  It is necessary for your SellWin clients to specify the
JBoss server host name in their preference properties exactly like the host name is specified in the jboss.properties file orthe clients
will not connect to the server.



Server Execution

After you deploy the SellWin 'EAR' file, you can start JBoss by the following command:

/apps/jboss-3.0.0_tomcat-4.0.3/bin> run.sh

Verify that SellWin's EAR has been successfully deployed by viewing the JBoss log.  Make sure
there are no errors.

Chat Server Execution

The current ChatServer executes in a separate JVM.  To start it, issue the following
command from your SellWin home directory:

cd /home/jmccormi/sellwincrm
ant run-chat-server

Test the Server Installation


From another client host, run the SellWin client, specify the SellWin hostname in the user's
preferences.  You should be able now to connect to the server.  If an error exists, verify that
you have typed the hostname the same as how the server was specified in the jboss.properties
file.  Also, make sure you can ping the SellWin server using the name you specified.

Wireless Installation

XML Library

The new wireless client makes use of an open source XML parser library available at http://kxml.org.
You will need to download the source files from that site and compile them on your development system
into a directory that should be added to your CLASSPATH.  The compiling of the wireless SellWin classes
will look for these XML classes.  The actual XML source files are bundled as a package called 'kXML2'.

Currently, i'm including the required XML class files in the ~/sellwincrm/wireBuild build directory
to simplify the build process.

Servlets

The SellWin wireless application uses servlets to talk to the SellWin server components.  There is
now a package named sellwin.servlet that contains a set of servlets that specifically handle the
communications of the wireless application.  These servlets are built and deployed as a WAR file
into the JBoss application server during the build process described below.

Wireless Package

The SellWin wireless application also makes use of a new package named sellwin.wireless.  This
package holds all the XML Java objects that make up the wireless protocol between the wireless
application on the MIDP device and the servlets that service each wireless request.  The classes
in this package are used by the servlets and the wireless classes on the MIDP device.  They are
compiled two different times, once for the MIDP device using a special 'preverify' compiler and
another time using the normal J2SE compiler for the servlets.

Java Wireless Toolkit

The Java Wireless Toolkit 1.4 (WTK1.4) was used to develop the wireless application.  This toolkit is
downloaded from the http://java.sun.com site.

Building

There are two new ANT targets in the build.xml script specifially for the wireless application.  

To compile the servlets and create the WAR file you will issue the command:

% ant make-war

To deploy the WAR file into the JBoss deploy directory you will issue the command:

% ant deploy-war

These two commands are only meant to deploy the servlet components of the wireless application and
do nothing for the MIDP device code preparation.

The actual code on the MIDP device is compiled using the special WTK (Wireless Toolkit) compiler.
To compile the device code you will issue the following command:

% cd wireBuild
% build_wireless.sh

Testing


To test the wireless application, you will need to build all components as noted above, then start
up the JBoss server.  You will see a message noting the deployment of the wireless application WAR
file.

The final step is to start up the wireless device emulator using the WTK tools as follows:

% cd wireBuild
% run_wireless.sh

Open App, Copyright 2002