/*  Copyright 2011 Jason Jones
 *
 *  Licensed under the Apache License, Version 2.0 (the "License");
 *  you may not use this file except in compliance with the License.
 *  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 *  Unless required by applicable law or agreed to in writing, software
 *  distributed under the License is distributed on an "AS IS" BASIS,
 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *  See the License for the specific language governing permissions and
 *  limitations under the License.
 */
 
BACKGROUND & ABOUT
================== 

Jessub (Java Essbase Substitutions) is a small, simple, and free utility for 
use in Essbase automation routines. Although there is nothing specific to 
Essbase in the files (i.e., it could be used with any process in which you 
want to replace a certain token in a file), it is a small evolution of a concept
that has served me well in many instances.

Simply put, Jessub will read in a template file that you create, search for
certain tokens, then write a new file with those tokens replaced with different
values. Generally speaking, the tokens will be the contents of a MaxL script
statement to update a substitution variable. In effect, we are generating a new
MaxL script on the fly and running it against the target Essbase server.

There are numerous ways that updating substitution variables can be achieved:
you can login to EAS and update them yourself. You could write a Java program
using the Essbase Java API and update them. You can use a MaxL script to update
them.

Generating a MaxL script is kind of a hybrid approach with a few useful 
characteristics. By not using the Java API, we don't have to worry about the
version of the Java Essbase JAR file, we just need to have the MaxL script
interpreter available. We are also saved from having to do custom programming.

Generating the MaxL script dynamically is a tried and true approach that has
served me well in many environments because it's extremely easy to setup, and 
has no dependencies that are hard to meet (a Java JRE and a MaxL interpreter).

The Jessub interpreter recognizes tokens written in a sort of "micro-language",
which provides for some simple ways to generate many kinds of variables. Quite
often the need to update substitution variables is timing-based, meaning that
the target value of the substitution variable has something to do with the date
or an aspect of the date, such as the month, day, or year. 

HOW TO USE
==========

Given an input text file template with Jessub micro-codes in it, we run Jessub,
pass in the file, the name of the output file, and any other parameters. Jessub
will read in the template, replace the tokens, and write the defined file to the
output.

For example, let's say the contents of our file look like this:

	The current day: ${Day_%1$td;NOW()}
	
The resulting output file will look like this (depending on day that the program
is run this will be different:

	The current day: Day_1
	
The format here is that a Jessub expression is a dollar-sign ($), followed
immediately by a squiggly bracket ({), the expression contents, then an ending
squiggly bracket.

The first thing inside the squiggly bracket is the format string that the 
Jessub expression will use. Although in the above example it looks complex, it's
actually just a normal Java format string that could (and is) used with the
String.format() function. In other words, we haven't invented an entirely new
and arcane syntax to use here: we are leveraging all of the power and effort 
that has gone in to developing Java string formats (which are based on C printf
string formats, and so on). The Java 6 string format page can be found here:

	http://docs.oracle.com/javase/6/docs/api/java/util/Formatter.html#syntax
	
After the string format, we have a semi-colon (;), followed by all of the 
arguments for the string format. There are three different types of arguments
that Jessub recognizes:

	NOW()
	ENV()

NOW()
=====

Since many substitution variable updates have to do with the date, there is the
NOW() function for generating a date. Whatever the date is when the script is
run, NOW() will resolve to the current date, and then we can use the Java
format string to get what we want. In the above example, the code "Day_%1$td"
is a Java format string that evaluates to "Day_" and then the %1$td resolves
to the day of the month from the date object that is passed in. As mentioned
on the Java format string description page, the %1 refers to argument one of
all of the arguments that are passed in. In addition to just grabbing the 
current time and date, we can also pass some parameters in to our NOW() function
to adjust the date in a certain way. We can adjust the current date by a certain
number of days, months, or years. For example, let's say that we want the 
contents of the substitution variable to be the previous date with regard to the
current day. We can simply adjust the date value:

	Yesterday: ${Day_%1$td;NOW(DAYS:-1)}
	
This is the same as our earlier example, except we are adjusting the days by
negative one ("go back in time from the current date by 1 day, then use that 
as the value to format with"). We can adjust by months and years to if we want:

	Some weird date: ${Day_%1$td;NOW(DAYS:-1,MONTHS:-1,YEARS:-1)}

This uses the date that is one year, one month, and one day prior to the current
date. 

ENV()
=====
We can get the string value of an environment variable, if we want. We just use
the ENV() function with the name of the environment variable.

	The path: ${%s;ENV(PATH)}
		
Multiple values
===============
We can format multiple values, just like a String.format() call, by separating
different parameters with a semi-colon:

	Multiple: ${%s %s;PARAM(foo);PARAM(bar)}

Running on the command line
===========================
We just need to run the Java jar from the command line and pass in the name 
of the files, plus any parameters we want:

	java -jar jessub-1.0.0-dist.jar inputfile.msh.template outputfile.msh
	
Automating
==========
Once we have our template setup properly, we can easily automate this in a batch
or shell file that might look like this:

	cd /d %~dp0
	java -jar jessub-1.0.0-dist.jar inputfile.msh.template outputfile.msh
	essmsh outputfile.msh
	
Other
=====
Jessub uses the excellent JodaTime library for working with dates. This library
has a much more sane programming interface than Java's native Date/Calendar
classes. JodaTime also has support for arbitrary calendar systems. Although I 
have not tried it, it is possible to develop a calendar plugin of sorts that
could be used to adapt a normal calendar to a business fiscal calendar of any
kind. For example, many businesses use a 13 period calendar for planning and
other purposes. Since the source code is open, you are free to experiment with
how this could work. Time permitting, I may attempt to develop it myself.

Building
========
Jessub is a Maven project designed for easy builds and updates. Simply run a 
Maven package command from the root project folder, and all files will be 
generated. The runtime JAR file has dependencies (Joda Time) built in so it 
can be run as a standalone JAR.

Thanks
======
Thank you for checking out this software. It is simple, but useful, and a good
administrator is a lazy administrator that wants to sleep in instead of 
updating substitution variables.

Jason Jones

