A framework to develop enterprise applications that need transactions, persistence, and a rich domain model.
Java
Pull request Compare This branch is 142 commits ahead, 583 commits behind fenix-framework:develop.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
adt-bplustree
adt-linkedlist
adt-skiplist Automatic Locality Hint generation Aug 22, 2013
archetypes Bump version to 2.10-cloudtm-SNAPSHOT Jul 16, 2013
backend-fenixjvstm Bump version to 2.10-cloudtm-SNAPSHOT Jul 16, 2013
backend-infinispan New load balance policy finished Sep 5, 2013
backend-jvstm-mem Transaction class support Aug 12, 2013
backend-mem Transaction class support Aug 12, 2013
backend-ogm Transaction class support Aug 12, 2013
bundle Bump version to 2.10-cloudtm-SNAPSHOT Jul 16, 2013
cloudtm-locality-hints
core
data-access-patterns Updated ISPN code generator to issue DAP instrumentation and added tr… Aug 8, 2013
dml-compiler L2 Cache implementation and tests Aug 6, 2013
dml-maven-plugin Bump version to 2.10-cloudtm-SNAPSHOT Jul 16, 2013
docs Externalize TreeMap in B+Trees to fix bug in Infinispan State Transfer Nov 21, 2012
hibernate-search Bump version to 2.10-cloudtm-SNAPSHOT Jul 16, 2013
indexes L2 Cache implementation and tests Aug 6, 2013
parent Updated ISPN code generator to issue DAP instrumentation and added tr… Aug 8, 2013
project
test Configurable exponential backoff on ISPN transaction restart Sep 2, 2013
txintrospector Bump version to 2.10-cloudtm-SNAPSHOT Jul 16, 2013
.gitignore Update .gitignore Mar 20, 2013
COPYING Cherry-pick merge with br2012. Feb 6, 2013
COPYING.LESSER Cherry-pick merge with br2012. Feb 6, 2013
COPYRIGHT.TXT Cherry-pick merge with br2012. Feb 6, 2013
EclipseFenixFrameworkCodeStyle.xml Reverting some dependencies versions/configurations to match the curr… Feb 6, 2013
README.md Merge branch 'big-refactoring-2012' into merge-cloudtm Jan 16, 2013
pom.xml Bump version to 2.10-cloudtm-SNAPSHOT Jul 16, 2013

README.md

Welcome to the Fenix Framework (FF)

Quick start

To create a sample application pre-configured with the FF, execute the following Maven command and follow the interactive mode:

mvn archetype:generate -DarchetypeGroupId=pt.ist -DarchetypeArtifactId=fenix-framework-application-archetype-clean -DarchetypeVersion=2.0-cloudtm -DarchetypeRepository=http://cloudtm.ist.utl.pt:8083/nexus/content/groups/public/

The parameters that you can give to the clean application archetype (using the -D switch) are:

  • fenixFrameworkVersion:
    • Description: The version of the Fenix Framework to use
    • Default: Same as the archetype's version.
  • backEndName
    • Description: The name of the backend to use. Some possible values are mem, ispn and ogm.
    • Default: mem
  • backEndGroupId
    • Description: The groupId of the backend module to use.
    • Default: pt.ist
  • backEndArtifactId
    • Description: The artifactId of the backend module to use.
    • Default: fenix-framework-backend-mem
  • backEndVersion
    • Description: The version of the backend module to use.
    • Default: Same as the archetype's version.
  • codeGeneratorClassName
    • Description: The code generator class provided by the chosen backend. Some possible values for each backend are:

      • mem -> pt.ist.fenixframework.backend.mem.MemCodeGenerator
      • ogm -> pt.ist.fenixframework.backend.ogm.OgmCodeGenerator
      • ispn -> pt.ist.fenixframework.backend.infinispan.InfinispanCodeGenerator
    • Default: pt.ist.fenixframework.backend.mem.MemCodeGenerator

If you go this way, then you just need to know how to Use the FF in your code. Alternatively, read this entire document for some more information.

Compiling

To compile all the modules in the FF and create one JAR per module, run this command:

mvn package

Installing

To use the FF in your application, you need the packaged JAR files. You can install them in your local Maven repository with:

mvn install

If you do not use Maven, just copy all the JARs produced with the mvn package command to your project and then

Developing with the FF

There are two aspects to this topic:

Make the FF accessible to your code

If, instead of starting from an archetype as mention in the beginning of this document, you opt to integrate the FF into your project, you need to make the necessary framework's modules available.

If you use Maven

If you use Maven to build your application, you can just depend on the Fenix Framework modules that you need, using something like the following in your pom.xml:

<dependencies>
    <dependency>
        <groupId>pt.ist</groupId>
        <artifactId>fenix-framework-backend-mem</artifactId> <!-- or any other module -->
        <version>2.0-cloudtm</version>                       <!-- or any other version -->
    </dependency>
</dependencies>

Additionally, you will probably want to hook the dml-maven-plugin to your build process, so that your domain classes get properly generated and post-processed. This can be achieved by adding the plugin to the build phase.

<build>
    <plugins>
        <plugin>
            <groupId>pt.ist</groupId>
            <artifactId>dml-maven-plugin</artifactId>
            <version>${fenixframework.version}</version>
            <configuration>
                <codeGeneratorClassName>${fenixframework.code.generator}</codeGeneratorClassName>
            </configuration>
            <executions>
                <execution>
                    <goals>
                        <goal>generate-domain</goal>
                        <goal>post-compile</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

Where the fenixframework.code.generator property could be set like this in your properties section of the POM file, e.g.:

<properties>
    <fenixframework.code.generator>pt.ist.fenixframework.backend.infinispan.InfinispanCodeGenerator</fenixframework.code.generator>
    <!-- <fenixframework.code.generator>pt.ist.fenixframework.backend.ogm.OgmCodeGenerator</fenixframework.code.generator> -->
    <!-- <fenixframework.code.generator>pt.ist.fenixframework.backend.mem.MemCodeGenerator</fenixframework.code.generator> -->
</properties>

Just make sure that fenixframework.version property is set in accordance with the version used for the other FF modules. This ensures that you use a plugin that matches the version of the framework you are using.

If you use any other build system

First make sure that the jars resulting from the mvn package are visible in your application's build and runtime classpaths, plus any additional dependencies. You can check for dependencies using the Maven dependency plugin:

mvn dependency:list

Then, you need to invoke the DML Compiler (class pt.ist.fenixframework.DmlCompiler) to generate the source base classes, before compiling your own code. After compilation you need to run the post-processor (class pt.ist.fenixframework.core.FullPostProcessDomainClasses) on your compiled classes.

Use the FF in your code

The docs directory in the top-level project contains a description of the Domain Modelling Language, which you need to use to describe your domain entities. Please refer to that documentation.

In the future, we plan to add more documentation to this section.

Backends

In-Memory Only (mem)

Hibernate OGM (ogm)

Direct to Infinispan (ispn)

Other Modules

Indexes

Please refer to the documentation in docs/dml-reference.md.

Data Access Patterns

This module adds the possibility of collecting information about the data access patterns performed by any target application built with the fenix-framework. When active, the code generator in this module adds, at the start of each setter and getter method, an invocation to a static method in the DAP framework that updates the statistical information regarding that particular read/write access operation.

To activate this module, the DML Compiler needs to be invoked with the property ptIstDapEnable set to true. This can be achieved either (1) via the command line by adding the switch -param ptIstDapEnable=true (no spaces around =) to the invocation of the compiler, or (2) via the maven plugin by adding that same parameter to the code generation phase as shown in the following example:

<build>
    <plugins>
        <plugin>
            <groupId>pt.ist</groupId>
            <artifactId>dml-maven-plugin</artifactId>
            <version>${project.version}</version>
            <configuration>
                <codeGeneratorClassName>${fenixframework.code.generator}</codeGeneratorClassName>
                <params>
                    <ptIstDapEnable>true</ptIstDapEnable>
                </params>
            </configuration>
            <executions>
                <execution>
                    <goals>
                        <goal>generate-domain</goal>
                        <goal>post-compile</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

When this module is active it can be configured via a properties file named dap.properties. If such file is used, it must be available in the CLASSPATH as a resource (at /dap.properties). If such file is not found, the Data Access Patterns module is still started with the default configuration, which does not have statistics collection active, and thus, the only performance penalty incurred is on a conditional test (which evaluates to false) on every get/set operation. Later, the data collection can be activated, e.g. via JMX.

Transaction Introspector

The TxIntrospector module enables internal information gathering during a transaction. When enabled, the programmer may obtain a pt.ist.fenixframework.txintrospector.TxIntrospector instance, and use it to query what were the new/modified objects/relationships for a transaction.

For more details, see txintrospector/README.md .

Hibernate Search

The hibernate-search module allows the indexing of domain objects for fast querying using the Hibernate Search framework.

For more details, see hibernate-search/README.md .