Habitat4J: Contextual Property Management for Java

• About
   Introduction

• Intro Docs
   Readme
   FAQ
   ChangeLog
   To-Do
   License

• Technical Docs
   JavaDoc
   Examples
   Bootstrap
   Schema Compat

• XML Schemas
   Server Identity
   Property List

• Habitat4J
   Latest Bin+Src [sig]
   Latest Binary [sig]
   Latest Source [sig]
   Latest Docs [sig]
   Latest JUnit [sig]

• Habitat4JWeb
   Latest Bin+Src [sig]
   Latest Binary [sig]
   Latest Source [sig]

• Habitat4JCrypto
   Latest Bin+Src [sig]
   Latest Binary [sig]
   Latest Source [sig]

• Misc Download
   PGP Public Key

• Mailing Lists
   Announce
   Support

--------------------------------------------------------------------------
Document: FAQ.TXT
Version:  $Id: FAQ.TXT,v 1.1 2008/08/15 01:33:38 cvs Exp $
Author:   Justin Yunke <habitat4j@productivity.org>
URL:      http://www.productivity.org/projects/habitat4j/
--------------------------------------------------------------------------
1.0.0.  INTRODUCTION & INDEX
--------------------------------------------------------------------------
Welcome to the Habitat4J Frequently Asked Questions (FAQ) document.

1.1.0.  THE BASICS
1.2.0.  HISTORY OF HABITAT4J
1.3.0.  ADMINISTRIVIA

--------------------------------------------------------------------------
1.1.0.  THE BASICS 
--------------------------------------------------------------------------
1.1.1.  What is Habitat4J?

Habitat4J is an XML-based property management system.  It consists of
two major components:  (1) A Server-Identity XML file, and (2) One or
more Property-List XML files or resources.

1.1.2.  What is the definition of a "habitat?"

Every application is deployed to an instance of actual or virtual
hardware.  Furthermore, that hardware represents several parameters,
including:  a unique name identifier (servername, IP address, ...),
an environment (Development, Unit Testing, Production, ...), an instance
enumeration (server #1, server B, ...), and other possible
parameters unique to that hardware instance.

The word "habitat" was selected because the word "environment" has
far too many meanings depending upon the context or organization.
It's rare that the word "habitat" appears when relating to Java
projects.

1.1.3.  What is a Server-Identity XML file?

A Server-Identity file, which defaults to the file system location:

  /server-identity.xml
  
...provides Habitat4J with server-wide information that will be used
to determine which properties will be loaded into the calling
application.  This file, in effect, defines the "Habitat."

1.1.4.  What is a Property-List XML file (or resource)?

A Property-List XML file, which can exist at a file system location or
a resource somewhere on the application's classpath, containing
application properties.  The properties are organized by context.

1.1.5.  How does Habitat4J work?

Habitat4J first loads the Server-Identity XML file, usually during
the bootstrap/initialization portion of the application.  Then, it
loads one or more Property-List XML files using the information in
the Server-Identity definition.  The result is that the application
can automatically configure itself based on information defined in
the "Habitat" (Server-Identity XML file) to which it is deployed.

--------------------------------------------------------------------------
1.2.0.  THE HISTORY OF HABITAT4J
--------------------------------------------------------------------------
1.2.1.  Where did the idea for Habitat4J come from?

When developing applications, it is typical that most staging environments
involve multiple servers or server instances, such as in a server "farm."
Add multiple applications, and property management can be complicated.

Most applications consist of two major deployment considerations:

  Application Code (JAR, WAR, EAR)
  Configuation (Properties)

Furthermore, applications often utilize the following staging
environments or categories:

  Development
  Unit Testing
  Production

An application's configuration may include different property information
per staging environment (above).  Ergo, it was quickly realized that the
server environment _itself_ often dictates which configuration is
appropriate for the deployed application.  One commonly used approach
involves keeping multiple property files in a file system and copying
them into place during the deployment process using ANT or batch/shell
scripts.

In organizations with multiple applications, the likelihood of a
standardized, consistent deployment process and related mechanism
is lessened due to different applications having different
requirements.

Habitat4J allows multiple applications to be deployed exactly the same to
any server instance and be automatically provided the appropriate
property entries without copying files or developing complicated
deployment scripts.

--------------------------------------------------------------------------
1.2.2.  How does Habitat4J work, by example?

Say there are three applications:

  Application A
  Application B
  Application C
  
...and three staging environments:

  Development
  Unit Testing
  Production
  
...and finally, there are six servers available:

  Qty 1 for Development
  Qty 2 for Unit Testing
  Qty 3 for Production
 
 It is decided to deploy them as follows:

  Development Server 1    Unit Testing Server 1   Production Server 1
  ----------------------  ----------------------  ----------------------
  Application A           Application A           Application A
  Application B           Application B           Application B
  Application C           
                          Unit Testing Server 2   Production Server 2
                          ----------------------  ----------------------
                          Application C           Application A
                                                  Application B

                                                  Production Server 3
                                                  ----------------------
                                                  Application A
                                                  Application C

Now, all applications need access to LDAP servers.  The applications
are configured as follows:

  Application       Development    Unit Testing     Production
  ----------------- -------------- ---------------- ------------------------
  Application A     ldap-dev-1     ldap-unit-1      ldap-prod-x,y,z*
  Application B     ldap-dev-1     ldap-unit-1      ldap-prod-x
  Application C     ldap-dev-2     ldap-unit-2      ldap-prod-y
  
  * Application A will use ldap-prod-x for Production Server 1, 
    ldap-prod-y for Production Server 2, and ldap-prod-z for Production
    Server 3.

Habitat4J would be configured as follows.  Let's start with the
a few examples of the ServerIdentity files:

** DEVELOPMENT SERVER 1 **

	<?xml version="1.0"?>
	<server-identity xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
		<application>
			<environment>Development</environment>
			<instance>
				<enumeration>1</enumeration>
			</instance>
		</application>
	</server-identity>

** UNIT TESTING SERVER 2 **

	<?xml version="1.0"?>
	<server-identity xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
		<application>
			<environment>Unit</environment>
			<instance>
				<enumeration>2</enumeration>
			</instance>
		</application>
	</server-identity>

** PRODUCTION SERVER 1 **

	<?xml version="1.0"?>
	<server-identity xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
		<application>
			<environment>Production</environment>
			<instance>
				<enumeration>1</enumeration>
			</instance>
		</application>
	</server-identity>

Next, let's take a look at the PropertyList file for Application A:

** APPLICATION A **

	<?xml version="1.0"?>
	<property-list xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
		<context environment="Development">
			<property name="ldap.server">ldap-dev-1</property>
		</context>
		<context environment="Unit">
			<property name="ldap.server">ldap-unit-1</property>
		</context>
		<context environment="Production" instanceEnumeration="1">
			<property name="ldap.server">ldap-prod-x</property>
		</context>
		<context environment="Production" instanceEnumeration="2">
			<property name="ldap.server">ldap-prod-y</property>
		</context>
		<context environment="Production" instanceEnumeration="3">
			<property name="ldap.server">ldap-prod-z</property>
		</context>
	</property-list>

When Application A is deployed to a server, Habitat4J reads the 
Server-Identity XML file, and then reads the PropertyList file using
information in the Server-Identity XML file to select the appropriate
properties.

Application A will use the following code to retrieve the ldap.server
property from a classpath resource:
 
   PropertyListManager.initialize("Application_A");
   PropertyListManager.loadPropertyList(
   		"org.productivity.applicationA.properties.property.xml"
   );
   String value = PropertyListManager.getProperty("ldap.server");
   
...and that's all!  The application does not need to keep track of
where it is deployed.  Simply making the call to Habitat4J's
PropertyListManager will retrieve all properties based on context
supplied by the Server-Identity XML file.
--------------------------------------------------------------------------
1.2.0.  ADMINISTRIVIA
--------------------------------------------------------------------------
1.2.1.  What license is Habitat4J released under?

The Lesser GNU Public License, or LGPL.  Read the enclosed LICENSE.TXT or
visit the website:

  http://www.gnu.org/copyleft/lesser.html

1.2.2.  Are there mailing lists?

There are two mailing lists; one for announcements, and one for support.
They are found here:

  http://www.elists.org/mailman/listinfo/habitat4j-announce
  http://www.elists.org/mailman/listinfo/habitat4j-support
  
The habitat4j-announce list is a low-volume list that will only be used
for information relating to new releases and other administrative
messages.  All messages to habitat4j-announce will be signed with the
Habitat4J Public Key.

The habitat4j-support list is a list open to all users and developers
using Habitat4J.

1.2.3.  Who currently maintains Habitat4J?

Justin Yunke <habitat4j@productivity.org>

1.2.4.  Where do I find new versions of Habitat4J?

http://www.productivity.org/projects/habitat4j/

1.2.5.  How can I contribute code to Habitat4J?

Join the habitat4j-support mailing list and state your idea in a posting.

1.2.6.  How can I contribute money to Habitat4J?

Great!  Contact habitat4j@productivity.org for instructions.

1.2.7.  What versioning scheme is used for Habitat4J?

Similar to GNU/Linux, Habitat4J uses major/minor/revision-style
versioning.  The major identifier increments when a considerable
update or rewrite has been performed.  The minor identifier is odd
for "development" versions, and even for "stable" versions.  The
revision identifier occurs when features are added (development)
and fixes are applied (stable).  Examples:

  0.9.0 : First development release.
  0.9.1 : First development release with features added.
  
  1.0.0 : First stable version.
  1.0.1 : First stable version with first round of fixes applied.
  
  1.1.0 : Second development release.
  1.1.1 : Second development release with features added.

--------------------------------------------------------------------------
End of Habitat4J FAQ
--------------------------------------------------------------------------
jpy   

Copyright (c) 2006 - Productivity.ORG & Habitat4J