Previous     Contents     Index          Next     
iPlanet Portal Server: Instant Collaboration Pack Release 3.0 Installation Guide



Chapter 4   Configuring iPlanet Instant Messenger


This chapter describes the steps to configure a client for iPlanet Instant Messenger.

This chapter contains:



iPlanet Instant Messenger Launch Overview

This section describes what happens when iPlanet Instant Messenger is launched, starting with the client entering a URL on the web server.


Launching iPlanet Instant Messenger from Java Plug-in

If you are using the JavaTM Plug-in version of iPlanet Instant Messenger, then the iim.html file performs the following actions:

  1. Downloads the following .jar files:

    • iim.jar

    • iimres.jar

    • iimnet.jar

  2. Passes to the iPlanet Instant Messenger applet the name and port of the server where the multiplexor is running.

  3. The default iim_mux.listenport is used by the applet, unless a different port was chosen at installation, in which case that port is passed to the application.

  4. The applet starts and talks to that server and port.


Launching iPlanet Instant Messenger from Java Web Start

If you are using the JavaTM Web Start version of iPlanet Instant Messenger, the iim.jnlp file performs the following actions:

  1. Downloads two .jar files:

    • iim.jar

    • iimnet.jar

  2. References the iimres.jnlp file, which downloads iimres.jar.

  3. Passes to the application the name of the server where the multiplexor is running.

  4. If a port other than the default was chosen at installation, it is passed to the application.

  5. The application starts and talks to the server and port.


Launching iPlanet Instant Messenger from iPlanet Portal Server

If you are launching iPlanet Instant Messenger as an iPlanet Portal Server application, the following occurs:

  1. The user clicks the iPlanet Instant Messenger link (either using Java Plug-in or Java Web Start) in the iPlanet Portal Server Desktop Application channel.

  2. The servlet file, iimcservlet.jar, uses the existing session ID from iPlanet Portal Server to set up a session with the iPlanet Instant Messaging multiplexor. The launch servlet fills in information taken from when the user logged into iPlanet Portal Server, for example: username, uid, token, if secure or not (SSL), whether the Java Plug-in or Java Web Start is being used, codebase, and so forth.

  3. iPlanet Instant Messenger is launched.

  4. iPlanet Instant Messenger connects to the iIM multiplexor and passes in the necessary credentials.



Requirements to Run iPlanet Instant Messenger

For the most recent information about software requirements for this product, see the iPlanet Portal Server: Instant Collaboration Pack 3.0 Release Notes, online at the following site:

http://docs.iplanet.com/docs/manuals/portal.html



iPlanet Instant Messenger Launch Methods


iPlanet Instant Messenger, written in Java, is iPlanet Instant Messaging Server's client that can be configured as either browser-based, running as an applet, or independent of a browser, running as a Java Web Start application.

The two ways to configure your client are:

  • Using Java Web Start (Solaris and Windows) - iPlanet Instant Messenger is launched from Java Web Start, which is an application launcher for Java 2 technology-based applications that are written to be web deployed. Once iPlanet Instant Messenger launches, your browser can be closed or used to locate other URLs without effecting the iPlanet Instant Messenger session.

  • Using the Java Plug-in (Windows only) - The applet is launched from the Java Plug-in, which is a code extension to the browser. To keep the iPlanet Instant Messenger session active, the browser window from which the applet was launched must remain open and cannot be used to locate any other URL.


    Note Solaris clients must use the Java Web Start configuration. Windows clients can choose to implement either the Java Web Start or the Java Plug-in configuration.


If you will have Windows clients, the section below provides information to help you decide which configuration method is best for your site.


Note To launch iPlanet Instant Messenger in the iPlanet Portal Server environment, click the appropriate link in the Applications channel in the iPlanet Portal Server Desktop.



Windows Launch: Java Web Start vs. Java Plug-in

The primary benefit of using the Java Plug-in is ease of installation. Microsoft Internet Explorer 5.0 will self-configure the plug-in the first time you launch iPlanet Instant Messenger by entering the appropriate URL in your browser. For Netscape Communicator, the plug-in must first be downloaded and installed.

Once the iPlanet Instant Messenger session is established using the plug-in, the browser must be dedicated to its use; that is, you can not locate any other URLs with this browser window, nor can you shut down the browser without terminating the iPlanet Instant Messenger session. Inadvertently losing the iPlanet Instant Messenger connection is potentially very inconvenient, especially for conferenced chat sessions.

To launch iPlanet Instant Messenger using Java Web Start, both the Java Runtime Environment and Java Web Start must be downloaded and installed. Thus, the one-time configuring of your Windows client with Java Web Start will be more time consuming than with Java Plug-in. However, using Java Web Start might prove far more convenient in the long run due to its browser independence.

With Java Web Start, you can shut down the browser, or use it for locating another URL without losing your iPlanet Instant Messenger connection.

Java Web Start supplies other benefits by:

  • Providing Java Runtime Environment management capabilities, so that Java Runtime Environment does not interfere with other runtime environments required by other applications.

  • Automatically updating any .jar files that have changed on the server since the last run.

  • Being only slightly larger than the Java Plug-in.

  • Adding a desktop icon for iPlanet Instant Messenger for quick loading.

In summary, if browser independence is important, then configure the Windows client using Java Web Start. (See "Removing iPlanet Instant Messenger" for more information.)

However, if initial ease of installation is of primary importance, and keeping a dedicated browser open for the iPlanet Instant Messenger session is not a problem, then configure the Microsoft Windows client with the Java Plug-in. (See "Configuring a Windows Client with the Java Plug-in" for more information.)



Configuring a Windows Client with Java Web Start


Use the following steps to configure a Windows client with Java Web Start:

  1. Download the Java Web Start for Windows self-extracting file from the following location. You are not required to download and install the JRE separately. It is bundled into Java Web Start.

    http://java.sun.com/products/javawebstart/download-windows.html

    Save the .exe file to a local disk directory, such as c:\temp.

  2. Install the Java Web Start.

    1. Open the directory where the .exe file was saved.

    2. Double click javaws-1_0_1-win-*.exe to start the install process.

      Follow the directions provided by the installer. It will update the Microsoft Windows registry and add an icon to your desktop. When done, you are then ready to run the iPlanet Instant Messenger client.

  3. See "Invoking iPlanet Instant Messenger" to run the iPlanet Instant Messenger client.



Configuring a Windows Client with the Java Plug-in

The following steps describe how to configure a Windows client with the Java Plug-in:

  1. Download the Java Runtime Environment 1.3 for Windows, which includes the Java Plug-in, and save it to a local disk directory, such as c:\temp.

    http://java.sun.com/products/archive/j2se/1.3.0/jre/index.html

    If you are using the Internet Explorer browser, it will handle this for you.

  2. Double click the saved .exe file to start the install process.

    Follow the directions provided by the installer. When done, you are ready to run the iPlanet Instant Messenger client.

  3. See "Invoking iPlanet Instant Messenger" to run the iPlanet Instant Messenger client.



Configuring a Solaris Client with Java Web Start

Use the following steps to configure a Solaris client using Java Web Start. You will need to download and install both the Java Runtime Environment and Java Web Start software.


Note You should create two directories to hold the Java Runtime Environment and Java Web Start software. This example uses the directories /home/user1/JRE and /home/user1/JWS.


  1. Download the Java Runtime Environment 1.3 for Solaris self-extracting binary file (j2re1_3_0-solsparc.bin) to a local disk directory, such as /home/user1/JRE, from the following location:

    http://java.sun.com/products/archive/j2se/1.3.0/jre/index.html


    Note While Java Web Start works with JRE 1.2, it is not recommended because of potentially serious performance issues.


  2. Download the Java Web Start .zip file to a local disk directory, such as /home/user1/JWS, from the following location:

    http://java.sun.com/products/javawebstart/download-solaris.html

  3. Install the JRE. (For more information, download the Java Runtime Environment file, README.sparc.)

    1. Change to the directory where you saved the self-extracting JRE binary file, for example:

      cd /home/user1/JRE

    2. Make sure that you set execute permissions on the JRE self-extracting file before trying to install, for example:

      chmod +x j2re1_3_0-solsparc.bin

      This example is for Java Runtime Environment 1.3.0. Be sure to check the exact file name that you downloaded.

    3. Run the self-extracting file to install the JRE software, for example:

      ./j2re1_3_0-solsparc.bin

      The JRE installs itself into the directory where you saved it earlier, in a subdirectory called j2re1_3_0.

    4. Write down the full path to the subdirectory where the JRE is installed. You will need this path in Step 4.

      In this example, the path would be /home/user1/JRE/j2re1_3_0.

  4. Install Java Web Start.

    1. Change to the directory where you saved the Java Web Start .zip file, for example:

      cd /home/user1/JWS

    2. Unzip the file, for example:

      unzip javaws-1_0_1_01-solsparc-int.zip

      This example is for Java Web Start version 1.0.1_01. Over time, a newer version might be posted, so be sure to check the exact file name that was downloaded.

      Java Web Start files are extracted, including one called install.sh.

    3. Run the Java Web Start install script, install.sh. For example, to install JWS on the local disk as /home/user1/javaws:

      cd /home/user1

      /home/user1/JWS/install.sh

      The installer asks you to supply the path to the Java Runtime Environment. You should have noted this path in Step 3.

  5. Close and exit any browsers to allow new registrations to be picked up.

  6. Restart your browser.

    Now you are ready to run iPlanet Instant Messenger.

  7. See "Invoking iPlanet Instant Messenger" to run the iPlanet Instant Messenger client.



Invoking iPlanet Instant Messenger

To invoke iPlanet Instant Messenger, you can use:

  • The index.html file, provided by iPlanet Instant Messenger. The index.html file provides buttons to launch both the Java Web Start and Java Plug- versions of iPlanet Instant Messenger. This file also has links to iPlanet Instant Messenger documentation.

  • A modified version of index.html, which you edit to your site's preferences.

  • An web page of your own design that provides a link to the version of iPlanet Instant Messenger you want your users to have access to.

  • An valid URL for iPlanet Instant Messenger, entered in the browser.


    Note To launch iPlanet Instant Messenger in the iPlanet Portal Server environment, click the appropriate link in the Applications channel in the iPlanet Portal Server Desktop. You do not use the index.html file, which is only for standalone deployments.



To Invoke iPlanet Instant Messenger

  1. Use the following URL to invoke iPlanet Instant Messenger.

    http://webserver:webserverport/subdirectory/filename


    Note Do not confuse the port on which the multiplexor listens for iPlanet Instant Messenger (in the iim.conf file, this is the iim_mux.listenport parameter) with the web server port above.

    The installation refers to the iim_mux.listenport as the "web client port" (default is 9909). You do not include this port in the URL to invoke iPlanet Instant Messenger.


    In this URL,




    webserver  

    Specifices the name of the web server where you installed the client files.  

    webserverport  

    Optional. Specifies the web server port if not the default (80).  

    subdirectory  

    Optional. Specifies the installation directory where the client files are installed. If the default web server document root directory was chosen at installation, then no subdirectory is necessary.  

    filename  

    Specifies the iPlanet Instant Messenger file to use:

    index.html - Provided by the product. The default contains links to launch both the Java Web Start and Java Plug-in versions.

    iim.jnlp - The jnlp file to launch just the Java Web Start version of iPlanet Instant Messenger.

    iim.html - The page to launch just the Java Plug-in version of iPlanet Instant Messenger.  

    For example, to invoke iPlanet Instant Messenger on Windows using Java Web Start, where the web server is i-zed.com, using port 123, with the default installation directory for the client files, the URL would be:

    http://i-zed.com:123/iim.jnlp

    To invoke iPlanet Instant Messenger on Windows using the Java Plug-in, where the web server is company22.com, using the default port (80), with an installation directory of iim, the URL would be:

    http://company22.com/iim/iim.html

  2. Depending on which version of iPlanet Instant Messenger— Java Web Start or Java Plug-in—you are using, the following happens:

    • Java Web Start - The first time you invoke the application, Java Web Start will download it into its cache, and a Security dialog will be presented. Accept the Security dialog.

    • Java Plug-in - The first time you invoke the Java Plug-in, a Java Plug-in Security Warning window opens, asking you if you want to run the signed applet.

      You must choose between: Grant this session, Deny, or Grant always. If you choose to grant for only this session, this window will open every time you invoke the plug-in, until you choose Grant always. If you choose Grant always, this window will not open again.

  3. For subsequent invocations of iPlanet Instant Messenger, you can:

    • Add the URL to your favorites.

    • Launch the application using the Java Web Start launcher icon on your desktop (Java Web Start version only).

    • Use the shortcut on your desktop. (Java Web Start asks if you want to put the icon on your desktop after the first or second time you invoke iPlanet Instant Messenger. Whether it asks the first or second time is a preference that can be set from the Java Web Start Edit menu.)


      Note When you launch iPlanet Instant Messenger from the iPlanet Portal Server Desktop by clicking the appropriate link in your Applications channel, the following happens:

      1. A new browser window opens with the servlet-supplied URL for either the Java Web Start or Java Plug-in version. When using the Java Plug-in version, do not close this new browser window and do not use it for other URLs. When using the Java Web Start Version, if the new browser window does not close automatically, you can close it or use it for other URLs.

      2. The Logon to Server window appears, using auto-logon. You will not have to enter any credentials, as they have been picked up from logging on to iPlanet Portal Server.

      3. When using secure mode, if this is the first time you have logged on to iPlanet Instant Messenger, the Netlet Connection Attempt Window appears.

      4. Click OK to accept the Netlet port, and check Don't Warn Again if you do not want to see this message on subsequent invocations.

      5. Once your connection to the iIM server has been established, the iPlanet Instant Messenger Main window appears.




Removing iPlanet Instant Messenger

This section describes how to remove iPlanet Instant Messenger from both Solaris and Windows client platforms. Should you want to remove the application from your client machine, follow the platform appropriate procedure below.


To Remove iPlanet Instant Messenger from Windows (Java Web Start)

  1. Launch Java Web Start Application Manager.

    For example, double-click the Java Web Start icon on your desktop.

  2. From the Applications menu, select:

    • Remove Shortcuts

    • Remove from Cache

  3. Close Java Web Start Application Manager.


To Remove iPlanet Instant Messenger from Windows (Java Plug-in)

  • Delete the java_plugin_AppletStore folder.

    For example, in Windows Explorer:

    • Click the java_plugin_AppletStore folder.

      For example, on Windows 98 the folder is located in: c:\WINDOWS\java_plugin_AppletStore

    • From the File menu, click Delete.


To Remove iPlanet Instant Messenger from Solaris

  1. Launch Java Web Start Application Manager.

    For example, double-click the javaws icon in the javaws directory.

  2. From the Applications menu, select: Remove from Cache.

  3. Close Java Web Start Application Manager.



Uninstalling Java Web Start or Java Runtime Environment

To uninstall either Java Web Start or Java Runtime Environment from your client machine, follow the platform appropriate procedure below.


To Uninstall Java Web Start or Java Runtime Environment on Windows

  1. From the Start menu, choose Settings and then Control Panel.

  2. Choose Add Remove Programs.

  3. Click the Install/Uninstall tab.

  4. From the list of products, select either Java Web Start or Java Runtime Environment, and click Add/Remove.

  5. Click Yes to uninstall the product.


To Uninstall Java Web Start on Solaris

  1. Delete the javaws directory.

  2. Edit your ~/.mime.types file.

    Remove any lines containing application/jnlp or application/x-java-jnlp-file.

  3. Edit your ~/.mailcap file.

    Remove any lines containing application/jnlp or application/x-java-jnlp-file.


To Uninstall Java Runtime Environment on Solaris

Delete the directory in which you installed the Java Runtime Environment. The default directory is: j2re1_3_1.



Troubleshooting iPlanet Instant Messenger Problems


Use the following information to help solve issues with client installations:


Difficulty Loading Resources - Proxy Settings

In a network environment, which has a firewall between your computer and the internet, if the Java Web Start has not been configured with the right proxy settings, you can experience difficulty loading resources.

Java Web Start can typically pick proxy settings up automatically by querying the system or the default browser. However, if the settings are configured using a JavaScriptTM file this is not possible.

You can set the proxies manually by using the Preference panel in Java Web Start's Application manager.


Java Web Start Does Not Start - mime.types for JNLP

If, instead of Java Web Start starting, you get the iim.jnlp file displayed in the browser, then you need to edit the web server's mime.types file to include a line for JNLP.

  • For iPlanet Web Server, the default location for this file is:

    /usr/netscape/server4/https-xxx/config/mime.types

    where xxx is your web server instance name.

    If not already present, add the following line:

    type=application/x-java-jnlp-file   exts=jnlp

    Restart the http-xxx server for this change to take effect.

  • For Apache Web Server, the mime.types file, located in the Apache Web Server configuration directory (its location is site-specific), should be edited to include the line:

    application/x-java-jnlp-file jnlp


Previous     Contents     Index          Next     
Copyright © 2001 Sun Microsystems, Inc. All rights reserved.

Last Updated December 04, 2001