How Do I

Launching a module

A module can be launched from command line or from the INGENIAS IDE. Despite the environment, if the module needs templates, these have to be available from the CLASSPATH or included in the same jar where the module is in.

To launch from command line

java -cp ext/mymodule.jar YOURMODULECLASS specificationFILE

To launch it from the IDE it is enough to deploy your jar in the ext folder and select the tool or code generator from the module menu entry.

To be able to launch a module from the command line, it should include a main method like the following, extracted from the HTMLDocumentGenerator.java

public static void main(String args[]) throws Exception {
             ingenias.editor.Log.initInstance(new PrintWriter(System.out));
             HTMLDocumentGenerator html = new HTMLDocumentGenerator(args[0]);
             html.run();
             System.exit(0);
}

The most important parts are:

  • Initialisation of the code generator with an argument. This argument is supposed to contain the path of the specification file to be processed.
  • Initialisation of the Log class. This class is used for loggin into the IDE. Please, read next section
  • Invocation of the code generator. The method to call is the run method.

Writing in the IDE

From a module is possible to write output to the IDE. Just by using ingenias.editor.Log class. This class implements a singleton pattern, so with:

ingenias.editor.Log.getInstance()

You can obtain an object with methods to log to the IDE messages window. Logs can be conventional or error logs. The first ones are presented in the IDE with the regular style (12 point letter and black foreground), the second with error style (14 point bold letter and red foreground).

On using a module from console, do not forget to initialise properly the Log before anything else

ingenias.editor.Log.initInstance(new PrintWriter(System.out));


This line will redirect any output to the standard output. The Log supports also handling two outputs (error and standard).

ingenias.editor.Log.initInstance(new PrintWriter(System.out), new PrintWriter(System.err));

In the error output, a developer can dump internal messages as well as error messages. There are methods for both (logSYS and logError). To dump a module's output, the log method should be used.

INGENIAS IDE provides different output format for logSYS and logERROR. LogERROR messages are written using red ink and a bold font. LogSYS are written using a conventional format (no bold and black ink). Log messages appear in the module output panel

Each message appears with a time stamp.

Writing a module

A tool is a module that traverse the diagrams trying to generate some kind of output that do not require verification of the specification. Common examples of such generators are statistics report generators.

A code generator is a module that reads diagrams from a file or from the INGENIAS IDE, that is able to determine whether current specification can be mapped to code, and perform the mapping.

Declaring the module

A module is a java class that implements ingenias.extension.BasicTool or ingenias.extension.BasicCodeGenerator. However, to save effort, we have created some classes that implement some of the methods of these interfaces. These classes are ingenias.editor.extension.BasicToolImp and ingenias.editor.extension.BasicCodeGeneratorImp. Choosing one or the other determines if you are developing a tool or a code generator

class MyModule extends ingenias.editor.extension.BasicToolImp{

 

 

Templates and code generator

Data extracted from a specification maps to a template. A template is a file that contains a program written in any programming language and that has been tagged. The tagging of the file determines what parts can be replaced with information from the diagram. So the template can be understood as a XML file that satisfy a concrete DTD:

Since almost every programming language uses symbols forbidden in XML (<,>.&), we decided to hide XML marks (transforming < and > into @ symbols), and translate the file to a valid XML format only when it is required. More details are available in the templates section.

Traversing diagrams

It is evident that not any piece of data can fit into this template. Only concrete parts of the specification find their place in the final code. So during the process we have to ask ourselves, am I getting all the information that my template requires? can this information originate a conflict in the final code?. For instance, if my template implements a workflow, should I allow to have multiple initiator tasks of the workflows? If my code does not and the specification declares that there are two initial tasks, then I can say that according to my template the information from the specificiation is not be correct.

So a code generator needs templates to perform the code generation task. Also a code generator has to traverse different diagrams. This traversal is possible with the ingenias.generator.browser.Browser interface returned by ingenias.generator.browser.BrowserImp through a singleton pattern (see examples).

Traversin the diagram can be as simple as the following

1. Obtaining an instance of a Broser

Browser browser=BroserImp.getInstance()

2. Obtaining the diagrams

Graph[] gs=browser.getGraphs();

3. Traversing diagrams

for (int k=0;k<gs.length;k++){
 Graph g=gs[k];
... Do something with g ...
}

A complete example of such traversal is the Entities Usage statistics. This kind of traversal is common in report generation and is associated with classes realizing BasicTool interface.

Most frequently, it is more recommendable to let yourself guide by the target architecture. For instance. Let us suppose that the template is somthing like

<repeat id="first">
 System.out.println(" result of the boolean expression "+<v>second</v>);
</repeat>

<repeat id="third">
 x=x+1;
</repeat>

 

Our code generator would traverse the diagram with something like:

.....

public Sequences generate(){

Sequences seq=new Sequences();

obtainInstancesofFirst(seq);

obtainInstancesofSecond(seq);

return seq;

}

...

As readers can see, information is generated in the same order as the template has determined. This is not necessary, but is appropriate as a guide. Obtaining information from diagrams to fill in the data required by repeat "first" and "third" may require traverse several graphs. A example of such traversal is the Servlet generation and JADE generation. Also more details about templates and code generators are available in the templates section.

Deploying a module

CD into your binaries folder (like cd classes folder) and write

jar -cvf mymodule.jar [binaries] [templates]

for instance, let's suppose that my module has one file named ingenias.codeproc.ExampleReportGenerator

jar -cvf example.jar ingenias/codeproc/ExampleReportGenerator.class

For instance, let's suppose that my module has one file named ingenias.codeproc.ServletBasedWorkflowsimulator and one template named templates/servlet.xml

jar -cvf servlet.jar ingenias/codeproc/ServletBasedWorkflowsimulator.class templates/servlet.xml


In case you have more files, just write them down in a list. It is important that any file outside of the default ingenias distribution is included into your jar. Later, this jar is copied into your ext folder. It is important that you do not create it directly in the ext folder when the IDE is running. This would produce an invalid header error.

Since deploying a module can require several instructions, we recommend you to use ANT instead. Next section provides more details

Using the ant to deploy a module

Ant is a tool similar to makefile but portable and extremely powerful. With ant you can compile, create your jar file and move it to the deployment folder very easily. Of course ant can do much more. Just have a look at http://ant.apache.org

In Ingenias IDE we use ant to facilitate the compilation of the enviroment but also to facilitate the compilation and deployment of our modules.

To compile and deploy a module you can use the following

<project name="ingenias" default="modhtmldoc" basedir=".">
  <property name="src" location="src"/>
  <property name="output" location="output"/>
<property name="modhtmldoc" location="modules/srchtmldoc"/>

<property name="moddeploy" location="ext"/>
 <property name="build" location="classes"/>
               <property name="temp" location="tmp"/>
 <property name="dist" location="classesprod"/>
 <target name="modhtmldoc">
               <delete dir="${temp}"/>
               <mkdir dir="${temp}/templates"/>
 <depend srcdir="${modhtmldoc.dir}"
               destdir="${temp.dir}"
               cache="depcache">
               <include name="**/*.java"/>
          </depend>
  <javac
               compiler="modern"
               depend="true"
               destdir="${temp}">
               <src path="${modhtmldoc}"/>
               <classpath>
               <pathelement path="${classpath}"/>
               <pathelement path="${build}"/>
               <fileset dir="lib">
               <include name="**/*.jar"/>
               </fileset>
               </classpath>
               </javac>
  <copy todir="${temp}/templates">
               <fileset dir="${modhtmldoc}/templates">
               </fileset>
               </copy>
  <jar jarfile="${modhtmldoc}/modhtmldoc.jar" basedir="${temp}"/>
  <move file="${modhtmldoc}/modhtmldoc.jar" toDir="${moddeploy}"/>
 </target
</project>

We assume that you have a lib folder that contains ingenias distribution libraries and that there is a folder named templates in your module source files that contains the templates your module needs, if it needs any module. To execute this script you need to have it in a file named "build.xml". Also, of course, you need to have installed ant in your system (see the home of ant for further instructions). To compile and deploy this module we just write

ant modhtmldoc

in the command line, and it does everything is needed. You can check that this script runs perfectly on windows and linux.