Commit 12d4d54a authored by Munilla Christophe's avatar Munilla Christophe
Browse files

create TAG JULIAC_2.4.1 to use the osgi-revision module in FraSCAti

parents
============================================================================
Juliac
Copyright (C) 2007-2011 INRIA, USTL
This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
License as published by the Free Software Foundation; either
version 2 of the License, or (at your option) any later version.
This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public
License along with this library; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
Contact: fractal@ow2.org
Author: Lionel Seinturier
============================================================================
============================================================================
Juliac
Copyright (C) 2007-2011 INRIA, USTL
This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
License as published by the Free Software Foundation; either
version 2 of the License, or (at your option) any later version.
This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public
License along with this library; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
Contact: fractal@ow2.org
Author: Lionel Seinturier
Contributors: Philippe Merle, Frédéric Loiret, Romain Rouvoy, Christophe Munilla
============================================================================
Juliac 2.4
----------
Juliac is a framework for generating and compiling the source code of the
infrastructure (so called membranes) which is needed to run a Fractal/Java
application. The application can then be run without having to use ASM to
generate on-the-fly classes for interfaces, controllers and merge strategies.
Juliac is an alternative to Julia in cases where dynamic code generation and
loading is problematic. The idea behind Juliac is close to that of Think
(but for Java of course). Currently, four optimization levels have been
implemented in Juliac: MERGE_ALL, OO (controllers implemented as separate
objects), COMP (component-based control membranes) and ULTRA_MERGE. Juliac can
be configured to accept other user-defined optimization levels.
The name Juliac stands for "Julia Compiler" and was proposed by Philippe Merle.
Juliac is a free software distributed under the terms of the GNU Lesser
General Public license. Juliac is written in Java.
Table of content
----------------
1. Requirements
2. Introduction
3. Compiling and installing Juliac
4. Running the sample applications
5. Compiling and running your own applications
6. References
1. Requirements
---------------
Maven 2.0.x is required to compile and run Juliac.
See http://maven.apache.org for instructions on downloading and using Maven.
2. Introduction
---------------
Juliac is composed of 9 modules:
- all: the superset of all Juliac Maven artifacts (excluding extension)
- core: the code generation framework
- examples: sample applications and tests
- extension: extensions to Juliac
- julia-mixed: pre-mixed Julia control membranes
- mojo: a Maven plugin for Juliac
- opt: the default optimization levels
- plugin: optional modules for Juliac (Fractal ADL, JDT, JDK 6, MIND ADL, Spoon)
- runtime: the library needed to run an application compiled with Juliac
The following basic samples applications are available in the examples module:
- comanche: the Comanche web server application
- helloworld: the Fractal Hello World application
In addition the examples/advanced directory contains some advanced samples. See
the README.txt in the corresponding directories to obtain more information about
these samples.
- comp-based-membrane: programming a custom component-based control membrane
- dream: examples with the Dream and COSMOS frameworks
- foobar-cases: FooBar examples
- helloworld-bin: binary components (compiled classes) with Juliac
- helloworld-scala: Scala components (contributed by Romain)
- jdk6: some examples illustrating the use of Juliac JDK 6 specific features
- large: large component assemblies
- mix: the Fractal Hello World application with different optimization levels
- osgi: some examples using the OSGi Equinox and Felix frameworks
- tests-conf: the Julia and Juliac conformance tests
- ultra-merge: examples with the ultra-merge optimization level
The extension directory contains some extensions to Juliac for the following
frameworks:
- dream: the Dream and COSMOS frameworks
- osgi: the OSGi Equinox and Felix frameworks
- tests-tools: a simple test framework for Juliac
3. Compiling and installing Juliac
----------------------------------
To compile and install Juliac in your Maven local repository, from the root
directory where Juliac has been installed, type:
mvn install
4. Running the sample applications
----------------------------------
To compile and run the sample applications, type:
cd examples/xxx (where xxx is the directory name of the sample)
mvn -Pjuliac:run
5. Compiling and running your own applications
----------------------------------------------
The quickest way for using Juliac is to mimic the organization of the
examples/helloworld module. The source and the resources of the application
should be put under respectively, src/main/java and src/main/resources.
5.1 Compiling
-------------
A Maven plugin is available for compiling applications with Juliac. As
illustrated in the examples/helloworld module, the plugin can be configured as
follows:
01 <build>
02 <plugins>
03 <plugin>
04 <groupId>org.objectweb.fractal.juliac</groupId>
05 <artifactId>maven-juliac-plugin</artifactId>
06 <version>2.3.1</version>
07 <executions>
08 <execution>
09 <id>juliac-compile</id>
10 <phase>generate-sources</phase>
11 <goals>
12 <goal>compile</goal>
13 </goals>
14 </execution>
15 </executions>
16 <configuration>
17 <opts><opt>OO</opt></opts>
18 <srcs><src>src/main/java</src></srcs>
19 <mixins><mixin>org.objectweb.fractal.julia:julia-mixins:2.5.2:sources</mixin></mixins>
20 <adls><adl>example.hw.HelloWorld</adl></adls>
21 </configuration>
22 </plugin>
23 </plugins>
24 </build>
Lines 17 to 20 in the <configuration> section particularly matter for the
configuration of Juliac. The following tags are supported:
- <opts> optimization levels,
- <srcs> list of directories containing the source code of the application,
- <mixins> list of source code artifacts for the implementation of control
membranes,
- <adls> list of Fractal-ADL types to be compiled by Juliac.
See http://fractal.ow2.org/juliac-mojo for additional information about the
Juliac Maven plugin.
5.2 Running
-----------
Once compiled with Juliac, applications can be run with the
org.objectweb.fractal.juliac.runtime.Juliac Fractal provider class. The
<juliac.run.component> and <juliac.run.interface> properties allow specifying
respectively, the component and the interface to invoke. These properties
configure the juliac:run profile which is defined in juliac/pom.xml.
For example, when configured with:
<juliac.run.component>example.hw.HelloWorld</juliac.run.component>
<juliac.run.interface>r</juliac.run.interface>
the command:
mvn -Pjuliac:run
launches the example.hw.HelloWorld component by invoking the interface named r.
5.3 Optimization levels
-----------------------
Four optimization levels have been implemented and may be specified in the <opt>
tag:
- COMP: component-based control membranes (Juliac version of Koch),
- MERGE_ALL: a class which merges the content, the control and the interceptors
is generated for each component,
- OO: controllers are implemented as independent objects,
- ULTRA_MERGE: a non-reconfigurable version of the application is generated in
one unique class.
In addition, a custom optimization level may be specified. In this case, the
value of the <opt> tag must be the fully-qualified name of a class which
implements the org.objectweb.fractal.juliac.FCSourceCodeGeneratorItf interface.
6. References
-------------
- Cosmos : http://picoforge.int-evry.fr/projects/svn/cosmos
- Dream : http://dream.ow2.org
- Equinox : http://www.eclipse.org/equinox
- Felix : http://felix.apache.org
- Fractal : http://fractal.ow2.org
- Fractal ADL : http://fractal.ow2.org/fractaladl
- Julia : http://fractal.ow2.org/julia
- Maven : http://maven.apache.org
- MIND : http://mind.ow2.org
- OSGi Alliance : http://www.osgi.org
- Scala : http://www.scala-lang.org
- Spoon : http://spoon.gforge.inria.fr
For any question, please contact: fractal@ow2.org
Date of creation of this file: June 4, 2007.
Last modified: March 26, 2011.
Juliac 2.4
----------
* OSGi/Knopflerfish support (contributed by Christophe Munilla)
* API refactoring
* bug fix when generating the membrane factory: support membrane types where the
first type is not necessarily the component control interface
* Juliet annotation definitions moved to Fraclet
* new service for generating proxy (interface and interceptor) implementations
(requested by Remi M and Philippe)
* multiple ADL parsers support
* move to Fraclet 3.3
Released on April 7, 2011
Juliac 2.3
----------
* API refactoring
* extended code generation framework (contributed by Romain)
* Juliet annotation framework for defining membranes
* new testCompile goal in the Juliac MOJO for the generate-test-sources phase
Released on February 5, 2011
Juliac 2.2.6.1
--------------
* new gracefulExit option in the Juliac MOJO configuration to exit without
throwing an exception even if errors are reported
Released on October 27, 2010
Juliac 2.2.6
------------
* UnifiedClass API enhanced with new methods
* --igs option renamed to --icodegs
* new --iclassgs for specifying association between bytecode interceptor class
generator and source code ones
Released on October 23, 2010
Juliac 2.2.5.1
--------------
* fix proxy generation for generic methods to enable compilation with javac
Released on September 3, 2010
Juliac 2.2.5
------------
* enable configuring the ADL parser used by Juliac
* separate ADL parser code generation from optimization level code generation
* support for the MIND ADL
* better support for generic proxy generation with generics (contributed by
Jonathan)
* upgrade to Maven MOJO librairies version 2.2.1
Released on July 20, 2010
Juliac 2.2.4
------------
* new --genclassjar option for packaging compiled generated classes in a jar
* bug fix when generating interceptor implementations for generic interfaces
with more than one interceptor source code generator (reported by Philippe)
* when invoking Juliac from the command line, support component descriptors of
the form [component type, controller descriptor, content descriptor]
* new --compilationWarnings flag for reporting compilation warnings (requested
by Philippe)
Released on March 20, 2010
Juliac 2.2.3
------------
* artifact juliac-compiler renamed to juliac-core
* artifact juliac-dream-compiler renamed to juliac-dream-core
* new --compiler option for specifying the Java compiler to use
* new extension for compiling generated code with the JDK 6 Compilation API
* bug fix for proxy code generation associated with interfaces which specialize
the return type of an inherited method (reported by Loris)
* support for the Equinox OSGi platform in extension/osgi
Released on November 1, 2009
Juliac 2.2.2
------------
* MOJO
* optimization levels are specified with the tags <opts> and <namespaces>
* fix for artifacts with alphabetical version numbers (e.g. 2.4-alpha-4)
* configurable source code and bytecode compatibility levels
* a main(String[]) method is generated for assembly factories with a r/Runnable
server interface
* new example with the Scala programming language (contributed by Romain)
* optimization level source code generators
* ultra-merge: bug fix for architecture descriptors containing cycles between
components (reported by Frederic)
* OO: reduce the size of initializer classes by factorizing the code which is
common for each membrane (suggested by Philippe)
Released on September 22, 2009
Juliac 2.2.1
------------
* API changes: Juliac, optimization level source code generators
* tighter integration between the Spoon and JDT plugins
* the Spoon plugin retrieves the AST build by JDT via the JDT plugin
* library upgrades
* extension/dream: Dream Core 2.2
* extension/dream/examples/cosmos-helloword: Cosmos 0.1.5
* plugin/jdt: JDT 3.3.0.771
* plugin/spoon: Spoon 1.4.2
* extension/osgi
* Activator source code generator for bundling a Fractal assembly
Released on July 3, 2009
Juliac 2.2
----------
* API changes: optimization level source code generators
* bug fix in classpaths containing path names with white space characters when
invoking the JDT plugin
Released on May 7, 2009
Juliac 2.1.6
------------
* API changes: Fractal ADL plugin, optimization level source code generators
* new extension module for holding extensions to Juliac
* support source files stored in jar files
* new extension module for supporting OSGi/Felix osgiPrimitive membranes
* bug fix for the NORMAL mode of the simple interceptor source code generator
(reported by Alban)
* use the JDK logging API for reporting
Released on March 13, 2009
Juliac 2.1.5
------------
* new --pkgRoot option for rooting generated code in a given package
(requested by Loris)
* multiple optimization levels with the same controller descriptor prefix can be
specified
* manage internal interfaces when generating the code for mComposite components
* bug fix for the MOJO
* when managing dependencies retain the most recent version number of a
library
* artifact and module renaming for advanced Dream examples
* bug fix for plugin JDT on MacOS (contributed by Valerio)
Released on January 23, 2009
http://mail.ow2.org/wws/arc/fractal/2009-01/msg00014.html
Juliac 2.1.4
------------
* new advanced example for Dream/Cosmos
* lifecycle interceptors are generated per lifecycle controller
* new JuliacConfig class for handling several Juliac configurations
* handle component factories for large assemblies (reported by Judicael)
* due to the 64KB limit imposed by Java on method bytecode size, component
factories are split into several methods
Released on November 20, 2008
Juliac 2.1.3
------------
* refactor JuliacLoader
Released on October 27, 2008
Juliac 2.1.2
------------
* bug fix for the <mixin> tag of the MOJO (exclude transitive dependencies)
* add a classloader interface to the Juliac bootstrap component
Released on October 11, 2008
Juliac 2.1.1
------------
* bug fix for component interfaces with generics (reported by Damien)
Released on September 21, 2008
Juliac 2.1
----------
* structured configuration parameters for the MOJO
* <types> replaced by <adls>
* list-like tags for <adls> <modules> <mixins> <srcs>
e.g. <adls> <adl>...</adl> <adl>...</adl> ... <adl>...</adl> </adls>
* <components> MOJO parameter for generating the code corresponding to the
specified component types, membrane descriptors and content descriptors
* <compile> MOJO parameter replaced by <compileInput> and <compileGenerated> for
compiling respectively input and generated code (default values are true)
* --compile command line argument replaced by --compileInput and
--compileGenerated for compiling respectively input and generated code
(default values are false)
* handle absolute pathnames in command line arguments and MOJO parameters
* handle generic parameters when generating proxy classes
* Juliac API changes
* class Juliac: methods parseOptLevel and parseInterceptorGenerators replaced
by loadGenerators
* class JuliacParams extended with 2 new fields opt and igs of type String
with values taken from the corresponding configuration parameters
(either from the command line or the MOJO)
Released on September 12, 2008
http://mail.ow2.org/wws/arc/fractal/2008-09/msg00012.html
Juliac 2.0.2
------------
* bug fix with artifacts for default optimization levels
* use the plugin version number, not the project one (reported by Damien)
Released on July 5, 2008
Juliac 2.0.1
------------
* JDT compilation support: Improved reporting of error messages
* bug fix in code generation with inner types (reported by Fy)
Released on July 3, 2008
http://mail.ow2.org/wws/arc/fractal/2008-07/msg00012.html
Juliac 2.0
----------
* Maven groupId changed to org.objectweb.fractal.juliac
* Fractal ADL no longer mandatory (optional module)
* new juliac-runtime-comp module for applications with component-based membranes
* Juliac MOJO
* artifacts specified in the <mixins> and <modules> sections and artifacts for
default optimization levels (OO, COMP, MERGE_ALL and ULTRA_MERGE) are
automatically added to the classpath
* generated source code can be compiled by the regular Maven compile phase
Released on June 30, 2008
http://mail.ow2.org/wws/arc/fractal/2008-07/msg00005.html
Juliac 1.3
----------
* move to Fractal ADL 2.3
* custom class loader can be transmitted to the Juliac component factory
* new optimization level: ultra-merge
* package refactoring to increase independence between subsystems
* examples module refactored with basic and advanced samples
* artifact identifiers renamed with a juliac- prefix
* add a juliac-all artifact
Released on May 12, 2008
http://mail.ow2.org/wws/arc/fractal/2008-05/msg00003.html
Juliac 1.2
----------
* move to Fractal ADL 2.2
* custom architecture generation for user-specified optimization levels
Released on January 31, 2008
http://mail.ow2.org/wws/arc/fractal/2008-01/msg00143.html
Juliac 1.1
----------
* user-specified Fractal ADL factory and backend
(fractaladl.factory and fractaladl.backend system properties)
* interceptor on control interfaces
* FileSourceCodeVisitor interface in the source code visitor framework
* code generation for membranes independently of any content
* pre-mixed Julia control membranes (OO and COMP merge levels)
Released on December 23, 2007
http://mail.ow2.org/wws/arc/fractal/2007-12/msg00041.html
Juliac 1.0
----------
* 3 merge levels: OO, COMP and MERGE_ALL
* join use of different merge levels for the same application
Released on October 27, 2007
http://mail.ow2.org/wws/arc/fractal/2007-10/msg00104.html
core/
* dump generated files to disk only when one is sure that the generation process
is over and everything went right. The purpose is to prevent generating
incomplete code that can not be compiled. The issue arised with the
<gracefulExit> MOJO option. The issue was partially solved in r10816 (see
Juliac#generateSourceCodeOverride(ClassGeneratorItf)), by first generating
code in memory and then dumping the code onto disk once the generation is over
and has thus been completed without error. Yet the solution is not fully
satisfactory as it may happen that files in a group may be dependent from each
other, and in this case the compilation would still fail with a missing type
exception. The issue may arised for example when generating an initializer
class which references other generated types such as interceptor, interface or
controller implementations.
* when Juliac is invoked programmatically, support in memory code generation and
compilation when no value is defined for the --gensrc and --genclass
parameters. Retain the current behavior to generate in the default locations
for the MOJO and the command line.
* provide a --gensrcjar for packaging the generated source code in a jar file
* expose Juliac as a Fractal provider class.
The idea is to generated the source code during the first run of the
application in order to be able to reuse it for later runs.
* proxy generation
* fix generic type variable conflicts between the implemented interface and
the extended class. This conflict occurs for example in Tinfi when
generating proxies for generic interfaces (e.g.
BindingFactoryPlugin<E extends ExportHints, B extends BindHints>) from
the Binding Factory. In this case, the extended class is ServiceReference<B>
and the identifier B clashes with the one from BindingFactoryPlugin.
* provide a command line option for generating proxy (interface and interceptor)
implementations similar to the <proxy><signature><controllerDesc> parameters
available for the MOJO.
examples/advanced/
* add an example which uses the julia-fraclet module developed by Marc
extension/osgi/
* support OSGi properties (requested by Philippe)
* enable changing the bundle which is associated with a osgiPrimitive component
(suggestion by Valerio)
mojo/
* mvn clean checks the availability of the maven-juliac-plugin even though this
plugin is not required when performing mvn clean. This causes mvn clean to
fail if the MOJO has not been installed before (bug reported by Denis.)
opt/comp/
* provide a membrane factory
* interceptors on control interfaces (see OO)
opt/ultra-comp/
* use the parse method from the Fractal ADL plugin to retrieve a model of the
application. Traverse the model and replace:
* each primitive with the assembly corresponding to its membrane. The
primitive becomes the CContent component in the membrane.
* each composite with the assembly corresponding to its membrane. The
subcomponents should be referenced by the content control component of the
composite.
* do not add a content control component for composite membranes
(contentClassName == null ?)
* fix the status of the component control component in primitive membranes:
should it be removed and replaced by the MPrimitiveImpl of the content control
component?
* fix the status of the binding control component: should it be removed and
replaced by the MCompositeImpl of the membrane?
* if the content class implements LifeCycleController, add the corresponding
server interfaces to the content control component
* declare in the ADL of the lifecycle control component, the corresponding
optional client interfaces
* bind these interfaces
* fix the management of collection interfaces in MPrimitiveImpl and in
MCompositeImpl
opt/merge-all/
* merge all except content when the generic factory is invoked with an instance
* interceptors on client interfaces
* take into account .cfg Tree for instantiating a controller (see OO)
* interceptors on control interfaces (see OO)
opt/ultra-merge/core/
* handle synchronized methods
* handle synchronized(this) blocks
* provide an external configuration file to declare fields which hold
references to bound components (avoid being obliged to annotate fields with
@Requires)
* merge the code of some specified interceptors and/or controllers.
For example, it may be useful to inline a stat controller and its
interceptors. Such a use case is also needed by Ales and Frederic in the
Soleil-RTF project.
* support multiple different components with the same content class
* generate the code which contains a description of the architecture
* provide an API to retrieve a reconfigurable architecture from the merged
application. Note: transferring the application state from the merged
application to the reconfigurable one may not be so easy.
* evaluate and inline Fractal API invocations which do not modify the
architecture (e.g. getFcName())
* handle @Attribute annotations (suggested by Philippe)
* set the visibilities of attribute fields to final
* assign the values from the architecture descriptor to the initialization
expressions of the attribute fields
plugin/compiler/
* investigate new plugins for the compilation service
* janino <www.janino.net> (janino.jar - 463412 bytes)
* javac (jdk <= 1.5)
runtime-comp/
* provide a generic initializer implementation
runtime-merge-all/
* create this module with a o.o.f.juliac.runtime.merge_all package
* provide a generic initializer implementation
runtime-oo/
* provide a generic initializer implementation
To generate a binary distribution of Juliac:
mvn assembly:assembly
<assembly>
<id>bin</id>
<baseDirectory>juliac-${project.version}</baseDirectory>