Sample Hibernate Community Package for GlassFish v3

April 14, 2009 § 4 Comments

This is the second of a series of entries for people interested in producing packages for GlassFish v3 and hosting them on a live repository. The previous entry is IPS/pkg(5) crash-course for GlassFish v3 community package developers – Part 1. The next entry is here: Different strategies for building different packages (for GlassFish v3).

In this entry, we’ll go through the various parts required to make the Hibernate library available to end-users via the GlassFish v3 Update Center. This enables developers to add this library with a single step, thus avoiding various well-known jar/classloader issues. In a team of multiple developers, all can install the library in the same manner. This provisioning/install approach can be extended beyond the simple use of a library, but let’s start with something simple (more in other entries).

As introduced in the previous entry the glassfish-repo project is where it all happens. It provides a bootstrapping mechanism to abstract away the low-level details of creating and publishing IPS packages. Looking at the code hosted on glassfish-repo, you’ll find a top-level directory called packager/ which has sub-directories, each corresponding to an IPS package for GlassFish v3.

Setup

There’s a bit of setup described here for the following:

Update Center 2.x toolkit image. This is the cross-platform bootstrap code needed for creating, publishing, installing, and installing IPS packages. Get it from https://wikis.oracle.com/display/IpsBestPractices/Downloads. You will need to add pkg/bin and pkg/python2.4-minimal/bin to your PATH

and pkg/python2.4-minimal/lib and pkg/vendor-packages to LD_LIBRARY_PATH. You will not manipulate this toolkit yourself, a Maven plugin will do it for you.

Subversion (to check out the project code). This is not needed if you create your own local directory structure and don’t intend to publish back to this glassfish-repo project (although we’d love for you to share as much as you possibly can).

Maven 2.0.9 (everything is built using Maven2 in GlassFish v3 btw).
JDK 6

Key files and directories

There are really three key files and a directory for building an IPS package (this is documented here, so inlining it here for brevity) :

packager/package-name/pom.xml, the Maven config file to describe any dependency used when building the IPS package and the Maven profile/plugin that does all the packaging magic for you.
packager/package-name/build.xml, the ANT script that lays out the files on disk as they should be installed on the target GlassFish instance.

packager/package-name/src/main/resources/pkg_proto.py is called the prototype file and it contains the metadata required to build the package (name, version, license, and various attributes). The file format is well-documented here.

packager/package-name/target/stage is the staging area where the above ANT script should layout the files (with proper permissions) required by the IPS package. This is the root of a glassfish v3 install.

Before looking at the Hibernate example, consider studying packager/sample-package and using it as a template for your own packages.

Authoring the Hibernate IPS package example

The Hibernate package artifacts available from the glassfish-repo project has the following interesting content (click on the filenames to see the entire content):





packager/package-name/pom.xml contains the existing Maven profile and plugin definition encapsulating the IPS logic and adds a dependency to the hibernate-ips artifact (version 3.4.0.1) hosted on the java.net Maven2 repository :

   <dependency>
     <groupId>org.glassfish-repo.packager</groupId>
     <artifactId>hibernate-ips</artifactId>
     <version>3.4.0.1</version>
     <type>zip</type>
  </dependency>

packager/package-name/build.xml simply creates the target/stage directory and places the various libraries required by Hibernate into the lib/ directory, thus making the framework available to all the applications deployed in a domain or instance related to the GlassFish install for which users will be installing this package. Check this link for how to best use the “Common Class Loader” and decide where you need to place your jar files. Optionally you can use the <attachArtifact> tag to create an .ipstgz file (also discussed here) to archive the work done by this script.

packager/package-name/src/main/resources/pkg_proto.py contains pretty self-explanatory metadata for the IPS package (name, version, summary, description, and classification). In particular this is where you reference the location of the LICENSE.txt file (name and location can be different). dirtrees offers a way to take a subset of what is in the staging area by explicitly listing the directories that should be considered as being part of the IPS package. More documentation on the format of the file can be found here. Most of this is presented to the user when listing or installing the package. There is no dependency specified for this package. If you are not familiar with the Python syntax, I would suggest you look at IDE’s (such as NetBeans) offering Python support (color-syntaxing, etc…) to avoid debugging issues late in the build process.

packager/package-name/target/stage contains a single "glassfish" subdirectory that corresponds to the top-level directory in a GlassFish v3 prelude install and all the Hibernate JAR files are placed into the lib/ directory of the appserver install. This translates into having them placed in GLASSFISH_V3_INSTALL/glassfish/lib. Note that you shouldn’t assume the presence of any particular domain such as “domain1″ (more on that in another post).

Publishing and testing

Building and publishing is really a single-step process with IPS so you need to start a local repository using:

$ pkg.depotd -d ips-toolkit-dir/pkg -p 10000 --rebuild (running on part 10000. Full documentation here.

At that point, you can simply invoke maven from the package directory root (packager/hibernate in our case) with the appropriate repository URL, the path to the python binary, and the “ips” profile name :

$ mvn -Drepo.url=http://localhost:10000 -Dpython=ips-toolkit-dir/pkg/python2.4-minimal/bin/python -P ips

Once the package is successfully packaged, you can use GlassFish’s Update Tool (GF_V3_INSTALL/bin/updatetool) or the pkg CLI to :

• add http://localhost:10000 as an additional repository
• test the package

Another post will soon cover how packages can make their way on to the “live” repository.

If you’re interested in the maven-makepkgs-plugin logic/magic used build the IPS on your behalf, read the project’s main page, and this post by Kohsuke. You’ll find out how to build a package with a single src/proto.py file (no ANT) and getting most of it’s metadata straight from Maven.

Going further…

Upcoming entries will covers the process to actually publish your packages to the GlassFish http://pkg.glassfish.org/v3prelude/contrib/ repository. This entry covers Different strategies for building different packages (for GlassFish v3). Expect also more entries on building more advanced packages.

About these ads

§ 4 Responses to Sample Hibernate Community Package for GlassFish v3

  • Harsha says:

    I don’t understand why you had to use this packaging mechanism instead of going with the standard OSGi bundle repositories as implemented by felix, equinox, spring-dm.

  • James Branam says:

    Hi,
    My name is James Branam and I’m the NetBeans Community Docs Manager. Your blog entry would make a fantastic tutorial for our Community Docs wiki (http://wiki.netbeans.org//CommunityDocs). Would you be willing to contribute it? If you need any help or have any questions, please contact me at james.branam@sun.com. I look forward to hearing from you.

  • Nazrul says:

    Harsha:
    IPS (see http://www.ipshowto.org) provides multi-platform enterprise grade sophisticated patching mechanism including entitled access. This aligns well with our business model also. Based on our comparison (little biased) we picked IPS. OBR is on our radar also. The xml based repository scheme seemed similar to NetBean’s nbm (http://autoupdate.netbeans.org/nbm/nbm_package.html) style repository mechanism that GlassFish v2 used.
    Please feel free to join us at dev@glassfish.dev.java.net to discuss this (or any other topic). Thanks.
    –Nazrul

  • Alexis MP says:

    @Harsha: if the comment is related to providing the means to build the package as opposed to providing directly the package itself, then I think there’s a social benefit to asking for this.
    With everything there available to recreate the package, it’s fairly trivial for anyone to look into how it’s built, to enhance the package, to test it, and to submit it improvements.

What’s this?

You are currently reading Sample Hibernate Community Package for GlassFish v3 at Bistro! 2.0.

meta

Follow

Get every new post delivered to your Inbox.

%d bloggers like this: