Building Console


Introduction

The 389 Management Console as it is used in 389 Directory Server is truly made up of multiple pieces.

The 389 Management Console application itself is really much more than just a Java application. It was designed as a toolkit that can be extended to manage many different server applications. It provides many common Java classes that can be used to manage new applications.

389 Directory Server users are most familiar with is the 389 Directory Server Console. This is made up of all of the panels that allow to you manage your 389 Directory Server; basically it’s what comes up when you open up a 389 Directory Server instance from the topology panel. The 389 Directory Server Console is loaded by the 389 Management Console application.

Tools you need

In general, you’ll need to have the tools listed above in your PATH for your operating system. You should also have ANT_HOME and JAVA_HOME set appropriately for your system.

Components you need

These are built into Fedora. jss is part of EL5, and ldapjdk is available from jpackage.org

Console components

Building

Source

The sources for the 4 console components listed above can be found at Source - this has source tarballs and CVS information.

Building the Console Framework (idm-console-framework)

Use Ant

ant -Dbuilt.dir=/path/to/built/dir \
[-Dldapjdk.local.location=/path/to/ldapjdk.jar/dir] \
[-Djss.local.location=/path/to/jss4.jar/dir]

If all goes well during the build, the Console Framework jar files will end up in the “%{built.dir}/release/jars” directory. There is no “install” ant build target, so you must copy these jar files to their runtime location:

cp %{built.dir}/release/java/jars/idm-console-*.jar /path/to/runtime/jar/dir

You can also build html Javadoc API documentation by issuing the following command

cd console
ant -Dbuilt.dir=/path/to/built/dir javadoc

The Javadoc html files will be located in “%{built.dir}/doc”.

Building the 389 Console (389-console)

Use Ant

ant -Dbuilt.dir=/path/to/built/dir \
  -Dlib.dir=/path/to/shared/lib/dir \
  -Dclassdest=/path/to/jar/file/dir \
  [-Dldapjdk.local.location=/path/to/ldapjdk.jar/dir] \
  [-Djss.local.location=/path/to/jss4.jar/dir]

If all goes well during the build, the files will end up in the “%{built.dir}” directory. There is no “install” ant build target, so you must copy these jar files to their runtime location:

cp %{built.dir}/*.jar /path/to/runtime/jar/dir
cp %{built.dir}/389-console /path/to/runtime/bin/dir

Building Directory Server Console (389-ds-console)

To build the Directory Server Console, simply fire off Ant

cd ds-console
ant -Dbuilt.dir=/path/to/built/dir \
  -Dconsole.location=/path/to/console/framework/jars/dir \
  [-Dldapjdk.location=/path/to/ldapjdk.jar/dir]

If all goes well during the build, the files will end up in the “%{built.dir}/package” directory. There is no “install” ant build target, so you must copy these jar files to their runtime location:

cp %{built.dir}/package/389-ds* /path/to/runtime/jars/dir

The way the console works is that it downloads the directory server jar files from the admin server. If you want to use it this way, do this:

cp %{built.dir}/package/389-ds* %{_datadir}/dirsrv/html/java

cp /home/user1/source/built/package/389-ds* /usr/share/dirsrv/html/java

If you just want to run the directory console locally, you’ll need to copy these jars to your local directory:

cp %{built.dir}/package/389-ds* $HOME/.389-console/jars

cp /home/user1/source/built/package/389-ds* /home/user1/.389-console/jars/

You may need to rename the new jar file to match/overwrite the existing jar file name in /home/user1/.389-console/jars/

If you need the help files too, you’ll have to:

cp %{built.dir}/help/en/*.html %{_datadir}/dirsrv/manual/en/slapd
cp %{built.dir}/help/en/tokens.map %{_datadir}/dirsrv/manual/en/slapd
cp %{built.dir}/help/en/help/*.html %{_datadir}/dirsrv/manual/en/slapd/help

Building the Administration Server Console (389-admin-console)

To build the Administration Server Console, simply fire off Ant

cd admservconsole
ant -Dbuilt.dir=/path/to/built/dir \
  -Dconsole.location=/path/to/console/framework/jars/dir \
  [-Dldapjdk.location=/path/to/ldapjdk.jar/dir]

If all goes well during the build, the files will end up in the “%{built.dir}/package” directory. There is no “install” ant build target, so you must copy these jar files to their runtime location:

cp %{built.dir}/package/389-admin* /path/to/runtime/jars/dir

The way the console works is that it downloads the admin server jar files from the admin server. If you want to use it this way, do this:

cp %{built.dir}/package/389-admin* %{_datadir}/dirsrv/html/java

If you just want to run the directory console locally, you’ll need to copy these jars to your local directory:

cp %{built.dir}/package/389-admin* $HOME/.389-console/jars

If you need the help files too, you’ll have to:

cp %{built.dir}/help/en/*.html %{_datadir}/dirsrv/manual/en/admin
cp %{built.dir}/help/en/tokens.map %{_datadir}/dirsrv/manual/en/admin
cp %{built.dir}/help/en/help/*.html %{_datadir}/dirsrv/manual/en/admin/help

Using Eclipse

If you are doing any sort of non-trivial Console development or debugging, Eclipse can be very useful - http://www.eclipse.org/

You will definitely need the pre-requisites above, and the IDM console framework, 389-console and directory console code - you only need the admin console code if you plan to work on the admin server specific parts of the UI.

Once you get the source code, create a new project in Eclipse for idm-framework. Add the jss4.jar and the ldapjdk.jar to your project build and run classpath. Create new projects for 389-console, admin-console, and the ds-console.

In the 389-console directory that you cloned from git, do this:

$ mkdir bin # may already exist
$ cd bin
$ ln -s ../com

This will put the “branded” text and images into the default classpath.

In the idm-console-framework directory that you cloned from git, do this:

$ mkdir bin # may already exist
$ ant -Dbuilt.dir=bin prepare_build
$ cp ./src/com/netscape/management/client/console/versioninfo.properties\
 bin/com/netscape/management/client/console

The ds-console and admin-console classes will not work without the version information - they will throw an exception.

For running, the main class is “com.netscape.management.client.console.Console”

For the run arguments - there is a special flag to tell Eclipse to use the local versions of the classes - by default the Console will attempt to download the ds and as jar files from the admin server - use the flag “-D nojars” to tell the console to first look for the classes in the local ClassLoader.

I would also suggest the use of these arguments to the Console class as well “-x nologo -a http://localhost:9830/ -u admin -w yourpassword”

Walkthrough

Get the source

$ mkdir $HOME/source
$ cd $HOME/source
$ git clone ssh://git.fedorahosted.org/git/idm-console-framework.git
$ git clone ssh://git.fedorahosted.org/git/389/console.git
$ git clone ssh://git.fedorahosted.org/git/389/admin-console.git
$ git clone ssh://git.fedorahosted.org/git/389/ds-console.git

Prepare the console source

$ cd $HOME/source/console
$ mkdir bin  # may already exist
$ cd bin
$ ln -s ../com

Prepare the idm-console-framework source

$ cd $HOME/source/idm-console-framework
$ mkdir bin  # may already exist
$ ant -Dbuilt.dir=bin prepare_build
$ cp ./src/com/netscape/management/client/console/versioninfo.properties\
 bin/com/netscape/management/client/console

Launch Eclipse and setup the projects

Setup the idm-console-framework project

Setup the admin-console project

Setup the ds-console project

Setup the console project

Setup the Eclipse “Run/Debug Configuration”

Run configuration - Main

Run configuration - classpath

Run/Debug the console

Using NetBeans

The NetBeans setup is very similar to the eclipse setup. We will setup separate “Java Project with Existing Sources” projects for 389-console, 389-admin-console, 389-ds-console, and idm-console-framework.

Get the source

$ mkdir $HOME/source
$ cd $HOME/source
$ git clone ssh://git.fedorahosted.org/git/idm-console-framework.git
$ git clone ssh://git.fedorahosted.org/git/389/console.git
$ git clone ssh://git.fedorahosted.org/git/389/admin-console.git
$ git clone ssh://git.fedorahosted.org/git/389/ds-console.git

Prepare the console source

$ cd $HOME/source/console
$ mkdir bin  # may already exist
$ cd bin
$ ln -s ../com

Prepare the idm-console-framework source

$ cd $HOME/source/idm-console-framework
$ mkdir bin  # may already exist
$ ant -Dbuilt.dir=bin prepare_build
$ cp ./src/com/netscape/management/client/console/versioninfo.properties\
 bin/com/netscape/management/client/console

Launch NetBeans

Setup the projects

Do this for idm-console-framework, console, admin-console, and ds-console

Set the Build Libraries

Do this for the console, admin-console, and ds-console projects

Later, we will add /home/USER/NetBeansProject/idm-console-framework/dist/idm-console-frame.jar if we need to test changes to the idm-console-framework project.


Configure the idm-console-framework project



Build the Projects

Select Run from the NetBeans IDE menu, and then Build Project (idm-console-framework). This should build all the projects, and this is why we had to add the /usr/share/java/idm-console-framework*.jar files to the console, admin-console, and ds-console properties, because we build the subprojects first, and there is no idm-console-framework.jar yet.

Once we do this initial build we can go back and add /home/USER/NetBeansProject/idm-console-framework/dist/idm-console-framework.jar to the console, admin-console, and ds-console project libaries. Make sure this jar file is at the top of the list of jar files. Note, this step is only necessary if you have updated the idm-console-framework project.*


Running/Debugging the Console

Now that everything is built, simply choose Run or Debug from the NetBeans menu, do not forget to set your breakpoints.

Last modified on 1 March 2024