Besides a Java Development Kit (choose Java for Developers), you need to install Maven. If you are using the Eclipse IDE, you also need to install the respective Maven plugin, as explained in Eclipse Setup. See System requirements for detailed instructions.
Creating the Basis Application
We recommend adding a new OGEMA application as a new project in ogema-examples, if you checked out the sources. If you checked out the demokit only, choose any folder you like for application development. Browse to the desired directory and create a new application using the Maven archetype, as explained below.
Creation from Console
- Select or create a parent directory for your new project.
In your console, navigate to this directory and use the following command to start creating a new project:
- You will then see a list of all available ogema archetypes where you should select one of them by using the appropriate number (In the following picture, number 2 was selected).
- Maven will ask you for some extra information on your application:
- For groupId, we recommend you use "org.ogema.examples". In any case, it is strongly recommended to use lowercase letters only.
- For artifactId, chose whatever you think describes you application well (lowercase only, OGEMA naming convention uses minus-signs to separate words. For example: ogema-example-app)
- For version, chose anything you fancy (including the use of uppercase letters). We recommend "1.0-SNAPSHOT".
- For the package name, standard Java naming conventions apply (again, we recommend lowercase letters. For example: ogema.example.app)
- The application name (app-name) will be the name of the Java class generated in the package named in the previous step. Standard naming conventions for Classes apply (for example: ExampleApp).
- After entering all information you are forced to confirm your configuration. Press Y to accept or N to restart the configuration.
- Maven will then generate a new project inside your folder with the given configuration. The project is now ready for use and can be build with "mvn install".
Add your new application to your OGEMA installation
- In your rundirectory, locate the file config/config.xml
- Add a line corresponding to your new app to the initialization file. The relevant entries are the groupId, the artifactId and the version, which are the Maven coordinates of your project. The dir entry determines where the jar file will be copied if the -build option of the OGEMA launcher is used (and where the launcher looks for the file in case no Internet connection and no local Maven repository exists). Just use "bin/apps", unless you have a reason to chose something else .
Application development with OGEMA
To facilitate the application development with OGEMA, the demokit contains projects for NetBeans and Eclipse which provide run configurations to start the OGEMA demokit from your IDE. These helper projects can also be used to run the framework in debug or profiling mode without additional setup.
The launcher can also load projects directly from their maven build directories when their location is provided with the
--workspaceloc <dir> (short
-w) option. All maven projects which are referenced in the config file and can be found in a sub directory of the workspace directory will be loaded directly via
reference URLs. Check the actual bundle location with '
lb -l' on the OSGi console, it should start with
reference: for bundles loaded from the workspace. Also make sure to start the framework in clean mode (using
-clean) once when introducing the
Changes to files (including Java classes) in the build directories should be immediately visible in the running framework. Details depend on your IDE, however the default behaviour for Eclipse and NetBeans is to compile or copy files on save, so that the build directory (
target/classes/ inside the maven project dir) is updated. Some features, like code generated by annotation processors (e.g. the Felix SCR plugin used by the OGEMA archetypes) may require a full build (mvn install) of the project before changes show up in build directory, followed by a manual refresh of the bundle (
refresh <bundle ID>) via the console before changes can take effect.
The startup time of the framework may also be reduced by adding the switch
-o), which will stop the launcher from searching bundles online.
Older Text (partially redundant and deprecated)
Option 2 (only with proper configuration and installation):
In your console, browse to the directory where you want to create your project. Then, let Maven generate a new project by calling
|Basic Application (no GUI)|
mvn archetype:generate -DarchetypeGroupId=org.ogema.archetypes -DarchetypeArtifactId=ogema-app -DarchetypeVersion=2.0.0-SNAPSHOT
|Basic Application (with GUI)|
mvn archetype:generate -DarchetypeGroupId=org.ogema.archetypes -DarchetypeArtifactId=ogema-app-gui -DarchetypeVersion=2.0.0-SNAPSHOT
Creation from Eclipse
If you use Eclipse's in-built Maven you will have to right click on the ogema-archetypes project and choose "New -> Project...". Select "Maven -> Maven Module" and choose an appropriate module name (will be used as artifact id). It is recommended to uncheck the box add to working sets ogema-archetypes as the new project will not be an archetype itself.
Click on the "Next" button and choose "Add Archetype", copy and paste the settings into the dialog:
Archetype Group Id:
ArchetypeArtifactId: ogema-app-gui (or simpe ogema-app if you do not use gui)
Repository URL: https://www.ogema-source.net/artifactory/libs-release
Press ok, select "Inlcude snapshot archetypes"! and select the newly added archetype from the list and click on the "Next" button. If necessary modify the value for package (usually not necessary, this can be an arbitrary package path) and add a new value for the app-name property (following the Java naming convention for classes).
Modify the pom.xml
Chances are, Maven already added your new OGEMA application to the pom.xml of ogema-examples (or wherever you ran the mvn archetype:generate command from). It should appear as an entry in the modules section. If it doesn't, add it. The pom.xml of your application, residing in the newly-created subdirectory, needs some more adjustments. Merge it with the pom.xml of an existing OGEMA application (template-controller-app from ogema-examples is recommended), and make the following modifications on your merge:
Parent:Name the parent you want to use - keep ogema-examples if you don't know what to chose.
- Version: You can either keep the version entry the Maven tool generated for you, replace it with a new version of your choice (by changing the entry), or inherit the version from the parent project ogema-examples (by deleting the whole entry). OGEMA developers creating an application that is supposed to be part of the official releases, inherit from the parent project. Otherwise, the choice is up to you.
- Build: Comment out the entries JSPs, WebResources and MenuEntry. You may or may not need them later.
- Dependencies: Keep all. Consider adding the junit dependency created by Maven - or remove the unit test.
Import the project to Eclipse
Start Eclipse. Then chose File->Import->Existing Maven Projects and import your new project.
- OGEMA Demokit: Explains how to run OGEMA from a project directory (rundirectory)