Preparing
SDK/JRE
MC4J and the netbeans platform on which it runs require a 1.4+ SDK to build and run, though 1.5 is recommended for all features. (If you are going to build on 1.4, remove the "source" and "target" attributes from the javac command in the build.xml. These allow us to build against 1.5 for all 1.5 feature support, yet allow running under 1.4.)
Ant
The MC4J build process requires ANT 1.5+ in order to build. It can be downloaded from here.
MC4J codebase
This document is written for the current development code base and will be correct for the forthcomming version 1.2. Currently, you must check out the latest version from CVS to build.
Netbeans Platform
MC4J is built upon the Netbeans platform. In order to build a new MC4J application you must download a setup of the Netbeans platform. MC4J 1.2 beta 8 is built on the NetBeans Platform 4.0 final release available here. It has not been tested against the latest development or Q-builds for the 4.1 release.
Once you have a download of the platform, create a directory called "application" at the same level as the MC4J development directory. Then install the netbeans platform folder into that application folder and change its name to mc4j. Also, pull the contents from the platform4 directory up a level into the newly named mc4j folder. From there, the build process will do all the necessary customization of the netbeans install to turn it into MC4J. When your done, the directory structure should be similar to below:
Building
Start by editing the ant.developer.properties so that the "application.install" property is the full path to the netbeans folder that you changed to mc4j. In the above example it would be "/projects/MC4J Development/application/mc4j". Now you can run the following command in the mc4j build directory to get everything running "ant compile jars brand install run".
The ant commands accomplish the following:
"compile" - Runs javac against the java source using the libraries that come with the mc4j build download
"jars" - Build the necessary JAR archives that MC4J and the Netbeans platform uses to run. This includes the four NetBeans modules along with common jar files and libraries.
"brand" - Build the brand jar that alters the NetBeans platform UI to the MC4J look.
"install" - Copy all of the built archives into the correct places.
"run" - Starts the MC4J application for testing purposes.
"build-docs" - Will build the html documentation for the website.
Modules don't load
If you have a problem with a module that causes the NB platform to consider it broken, it will not be loaded the next time you start the application. In order to reactivate the module, open up the Tools -> Options dialog. Under Options -> IDE Configuration -> System -> Modules -> Infrastructure you will find the four MC4J modules. You can turn them on by selecting them and changing the enabled attribute to be true. They will be loaded immediately. You can also use this to disable any of the server support modules that you aren't using.
Running MC4J
MC4J no longer uses the Netbeans launcher functionality to startup. The freely available InstallAnywhere Now! product gives us a more seemless product for all platforms and so its launcher will be used for all future releases. For development purposes, the MC4J Ant build script now has a target for starting mc4j with all the same settings as the installer. While developing on MC4J, use "ant run" to start MC4J.
Classloaders
With the release of MC4J 1.2 beta 3 there have been some significant changes to the use of classloaders and how it affects connections to various JMX remoting agents. In prior releases, a seperate NetBeans module was created for each supported server. Each module Jar contained the necessary libraries, where possible, to connect to that type of server. The problem with this was that some of the libraries had licensing that precluded them from being shipped with MC4J and the rest just added to the application bloat. It also required hacks, like adding the weblogic.jar to the system classpath in order to support Weblogic connections.
The new model has an improved connection wizard and a more dynamic classloader capability that should simplify the development and the usage of MC4J. The console itself is now built as a single Netbeans module that support all servers. Within that module are the classes that are used to define and build new connections with custom classloaders for the server that is being connected to. The connection wizard will now let you select the application server you wish to connect to in the wizard and then will ask you to select the installation directory of that server so that the appropriate jars can be located. This only works for JBoss and Weblogic for now.
The system will let you select the installation directory and then will search for the special libraries required for that server (e.g. weblogic.jar for Weblogic). The wizard will then let you add additional libraries that may be required for that server or for any custom editors that you may wish to define. You may wish to add the libraries for your application so that executions will not get ClassNotFoundExceptions if they return one of your application classes.
In addition to the server classes, MC4J also has a special "mc4jlib" directory that it now uses to get the necessary libraries. This folder is designed to have two levels. Directly within the folder are the libraries that should be shared for all connections. MC4J ships with a number of these standard libraries for things like graphing and the general user interface functions. The "mc4jlib" directory can also contain subdirectories, named after the type of connection, to hold libraries specific to the type of server you are connecting to. For example, if you wanted to add a library such that it would be used for all JBoss connections, you would add it to a subdirectory called "JBoss". On creating the connection, MC4J will search for all libraries within the subdirectory named after the connection type and add them to the classloader that is created.
