Installing ContactCenters on Linux or UNIX

The installation is a three-steps process: install a Java Virtual Machine, unpack ContactCenters, and set up the environment. We will show these steps in more details.

If ContactCenters is already installed, an update can be performed simply by unpacking the new version at the same location as the old version. There is no need to redo the Java installation and environment setup.

Installing a Java Virtual Machine

Before using ContactCenters, one should install a Java Virtual Machine. The recommended JVM is Oracle's Java Runtime Environment, and can be found on the Oracle's Java SE downloads page. It is sufficient to download and install JRE for using the precompiled simulator, but JDK is necessary for programming using the ContactCenters library, which was used to build the generic simulator.

Note that GCJ, the default Java Virtual Machine bundled with many Linux distributions, is not compatible with ContactCenters. However, ContactCenters might work with IcedTea which is under development.

Testing if Java is already installed

One might test the installation of Java using a console. A console can be accessed several ways. For example, the GNOME Terminal can be accessed from GNOME by using the Terminal command in menu Applications, submenu Accessories. This opens a window allowing the user to type commands.

The console runs a shell which accepts commands corresponding to program names with arguments, separated by spaces. After writing any command on the console, the user needs to press the Enter key to execute it. The command java -version may be used to verify that the Java Virtual Machine is properly installed. Here, the program name is java while -version is an argument passed to the java program. The above command should produce an information message similar to the following one.

java version "1.6.0"
Java(TM) SE Runtime Environment (build 1.6.0-b105)
Java HotSpot(TM) Client VM (build 1.6.0-b105, mixed mode, sharing)

The displayed version should at least be 1.6.0. Java is not properly installed on the system if the above command produces an error message indicating that java is not a recognized command.

The exit command can be used to leave the console.

Installing or updating Java

For some GNU/Linux distributions, Java can be installed easily by using the builtin package manager. For example, with Ubuntu 7.04 and newer versions, the user simply needs to install the sun-java6-jdk package using the Synaptic package manager. The user might also have to type the command sudo update-java-alternatives -s java-6-sun on a console to set the default VM to Sun's rather than to GCJ. Using such an automated procedure to install JDK is recommended.

If JDK is not available as a package for one's Linux distribution, or if a more recent JDK than the one offered by the Linux distribution is needed, the manual installation procedure can be used. The following steps summarizes this generic installation process for the Oracle's JVM. The Web site Installation Notes provides detailed instructions for installing Java on GNU/Linux.

  1. Go to Oracle's Java SE downloads page.
  2. Click on the Download button next to JDK.

    This should correspond to the first Download button on the page.

  3. Select Linux as the Platform.

    If the command uname -m displays x86_64, one should instead select Linux x64 as the platform.

  4. Click on the check box to accept the license agreement.
  5. Click on the Continue button.
  6. Click on the link corresponding to the self-extracting file.
  7. Save the downloaded file on the hard disk.

    For example, the file can be called /tmp/jdk-6u2-linux-i586.bin.

  8. On a console, type the following commands as root.
    mkdir /usr/local/java
    cd /usr/local/java
    chmod a+x /tmp/jdk-6u2-linux-i586.bin
    /tmp/jdk-6u2-linux-i586.bin
    

    One may need to adapt the filenames and directories. It can also be necessary to prefix every line with sudo followed by a space to run the commands as root.

  9. Modify startup scripts to add the bin subdirectory in the PATH environment variable.

    For example, with Fedora Core, this can be done by creating a /etc/profile.d/java.sh file with contents

    #/bin/sh
    
    export JAVA_HOME=/usr/local/java/jdk1.6.0_02
    export PATH=$JAVA_HOME/bin:$PATH

    The path assigned to JAVA_HOME must be replaced with the true location of the JDK. For Ubuntu, this must be added to /etc/bash.bashrc.

Unpacking

The user must unpack the ZIP file to any location with the command
   unzip contactcenters-<DATE>.zip

This will create a contactcenters subdirectory containing all files of the distribution in the current directory. For example, if the command is called while the current directory is /usr/local/java, the base directory of ContactCenters will be /usr/local/java/contactcenters.

Note: If the library is unpacked by the root user to be installed for every user on a machine, the root user may need to adjust file permissions.

Setting up the environment

When using ContactCenters or any other third-party Java library, the user needs to tell Java how to locate the classes forming the library by configuring the CLASSPATH environment variable. Moreover, for convenience scripts to be used to call the simulator, the PATH environment variable must also be altered. Environment variables are properties passed implicitly to any executed program, including the Java Virtual Machine. The procedure to set these variables depends on the used shell. Most recent distributions of GNU/Linux use Bash by default, which is a kind of Bourne shell. Several UNIX flavors also use some types of Bourne shell. Older UNIX and GNU/Linux systems use C-Shell by default. The echo $SHELL command can be used to obtain the currently used shell.

For convenience, scripts are available to setup the environment for the user if the CCHOME environment variable is set prior to calling them. The following commands can therefore be used to setup the environment.

Commands for the Bourne shell

export CCHOME=<path to ContactCenters>
. $CCHOME/Contactcenters.sh

Here, <path to ContactCenters> must be replaced by the absolute path to the unpacked contactcenters subdirectory, for example /usr/local/java/contactcenters. The command lines should be added to an appropriate startup script for convenience; for example, in the file .bashrc in the home directory.

Commands for the C-shell

setenv CCHOME <path to ContactCenters>
source $CCHOME/Contactcentersrc

Here, <path to ContactCenters> must be replaced by the absolute path to the unpacked contactcenters subdirectory. The command lines should be added to an appropriate startup script for convenience; for example, in the file .cshrc in the home directory.

Other shells

If a different shell is used, the environment must be set up manually. This requires contactcenters.jar, ssj.jar, and colt.jar, located in the lib subdirectory of ContactCenters, to be referred to in the CLASSPATH environment variable. This variable is a colon-separated list of paths being searched by the Java Virtual Machine for classes. Moreover, the bin subdirectory of ContactCenters must be referred to in the PATH environment variable. This variable is a colon-separated list of paths being searched by the shell when a program is loaded.

Note on Java IDEs

Some Java Integrated Development Environments (IDEs) such as Eclipse and NetBeans do not use the standard CLASSPATH environment variable. These environments must be notified about the location of colt.jar, ssj.jar and contactcenters.jar manually. The procedure used to set these parameters can be found in the documentation of the specific Java IDE. If the archives cannot be located, the ContactCenters programs will not compile or not execute properly.

Testing the installation

If Java 6 is properly installed as tested above, the command mskcallcentersim may be entered on the console to test the installation of ContactCenters. After pressing Enter for validating the command, the user receives an information message similar to this:

Usage: java umontreal.iro.lecuyer.contactcenters.msk.CallCenterSim
          <call center data file name> <experiment parameter file>
          [<output file name>]

If this message appears, the installation is finished. Otherwise, the user needs to verify if the Java Virtual Machine is properly installed, and the environment variables are set.

The command cd $CCHOME/msk can be used to switch to the ContactCenters directory in order to load sample parameter files.

Here are the most common errors:

The java command cannot be found:
The Java Virtual Machine is not installed properly.
The command cd $CCHOME displays an error message or does nothing:
The CCHOME environment variable is not set up properly.
The mskcallcentersim command cannot be found:
The PATH environment variable is not set up properly. One can try
export PATH=$PATH:$CCHOME/bin
to set up the variable temporarily in a Bourne shell.
The mskcallcentersim shows NoClassDefFoundError errors:
The CLASSPATH environment variable is not set up properly. One can try
export CLASSPATH=.:$CCHOME/lib/contactcenters.jar
in a Bourne shell to set up the variable temporarily to run the simulator. The error can also appear if Java 5 is used instead of Java 6.