Introduction to a MUSIC middleware project

The MUSIC middleware is composed by a set of Java projects which typically generate an OSGi bundle. The MUSIC middleware is extensible by adding new project which add or replace services, as well as by offering new plugins (for communication, resources or context).

The main characteristics of a standard MUSIC project (for contributing to the middleware) are:

• It is a Java project
• It is an Eclipse project
• It is a Maven project
• It is an OSGi project
  

Standard structure for MUSIC middleware projects

A common template for the middleware projects is proposed to fulfil these characteristics. Basically it is based on a standard Maven project structure but with minor modifications. The following scheme depicts the structure, where the elements in bold mean that they require changes from the developer in order to adjust it to the target project:

[project]
|-- .project
|-- .classpath
|-- build.properties
|-- LICENSE
|-- pom.xml
|-- META-INF
|    |-- MANIFEST.MF
|-- src
     |-- main
     |    |-- java
     |    |    |-- org
     |    |         |-- istmusic
     |    |              |-- mw
     |    |                   |-- [project]
     |    |-- resources
     |         |-- META-INF
     |         |    |-- MANIFEST.MF
     |         |-- OSGI-INF
     |              |-- [component].xml
     |-- test
          |-- java
          |    |-- org
          |         |-- istmusic
          |              |-- mw
          |                   |-- [project]
          |                        |-- test
          |-- resources

Download the standard structure for the MUSIC middleware projects.

The main pecualiarities with respect to a standard maven project are:

• The files [project]/.project, [project]/.classpath, [project]/build.properties and [project]/META-INF/MANIFEST.MF make the Maven project also an Eclipse project. It is possible to import the project in Eclipse and use the Eclipse facilities to develop OSGi bundles (specially the MANIFEST wizard and the debug framework). The productivity is highly increased by working with Eclipse.
• The file [project]/LICENSE specifies the MUSIC license: LGPL2.1.
  

Detailed description of the relevant elements

The following subsections describe the most relevant elements in the standard structure for the MUSIC middleware projects.

[project]/.project

This file identifies the project as an Eclipse project, with support for Java, Maven and PDE (the Eclipse OSGi development framework). The developer needs to update the file in order to fix the name of the project.

<?xml version="1.0" encoding="UTF-8"?>
<projectDescription>
    <name>[project]</name>
    <comment></comment>
    <projects>
    </projects>
    <buildSpec>
        <buildCommand>
            <name>org.maven.ide.eclipse.maven2Builder</name>
            <arguments>
            </arguments>
        </buildCommand>
        <buildCommand>
            <name>org.eclipse.jdt.core.javabuilder</name>
            <arguments>
            </arguments>
        </buildCommand>
        <buildCommand>
            <name>org.eclipse.pde.ManifestBuilder</name>
            <arguments>
            </arguments>
        </buildCommand>
        <buildCommand>
            <name>org.eclipse.pde.SchemaBuilder</name>
            <arguments>
            </arguments>
        </buildCommand>
    </buildSpec>
    <natures>
        <nature>org.eclipse.jdt.core.javanature</nature>
        <nature>org.maven.ide.eclipse.maven2Nature</nature>
        <nature>org.eclipse.pde.PluginNature</nature>
    </natures>
</projectDescription>

[project]/.classpath

Eclipse uses this file to identify the directories for the source code and the directories for the build output, as well as the classpath. It is configured to work with the Maven standard project. No modification is required.

<?xml version="1.0" encoding="UTF-8"?>
<classpath>
    <classpathentry kind="src" path="src/main/java"/>
    <classpathentry kind="src" path="src/main/resources"/>
    <classpathentry kind="src" output="target/test-classes" path="src/test/java"/>
    <classpathentry kind="src" output="target/test-classes" path="src/test/resources"/>
    <classpathentry kind="con" path="org.eclipse.jdt.launching.JRE_CONTAINER"/>
    <classpathentry kind="con" path="org.maven.ide.eclipse.MAVEN2_CLASSPATH_CONTAINER"/>
    <classpathentry kind="output" path="target/classes"/>
</classpath>

[project]/build.properties

This file is used by Eclipse to build the deployment units (the OSGi bundles). No additional modification is required.

source.. = src/main/java/,\
           src/main/resources/,\
           src/test/java/,\
           src/test/resources/
output.. = target/classes/
bin.includes = .,\
               LICENSE,\
               META-INF/

[project]/pom.xml

The pom.xml file is the core of a project's configuration in Maven. The developer needs to update it according to the project information and the project dependencies. MUSIC middleware project typically use Maven project inheritance (see <parent> element) to simplify the configuration of the project. A complete reference to set it up is available at Maven's site.

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
                      http://maven.apache.org/maven-v4_0_0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>org.istmusic.mw</groupId>
        <artifactId>pom</artifactId>
        <version>0.3.0.0-SNAPSHOT</version>
        <relativePath>../pom</relativePath>
    </parent>

    <groupId>org.istmusic.mw</groupId>
    <artifactId>[project]</artifactId>
    <version>0.3.0.0-SNAPSHOT</version>
    <name>[project name]</name>
    <description>
        [project description]
    </description>
    <dependencies>
        <dependency>
            <groupId>org.istmusic.mw</groupId>
            <artifactId>music-model</artifactId>
            <version>0.3.0.0-SNAPSHOT</version>
        </dependency>
        <dependency>
            <groupId>org.istmusic.mw</groupId>
            <artifactId>music-kernel</artifactId>
            <version>0.3.0.0-SNAPSHOT</version>
        </dependency>
    </dependencies>
</project>

[project]/META-INF/MANIFEST.MF

This MANIFEST file is used by Eclipse in case that the developer debugs the project in the IDE. However, Maven uses the other MANIFEST file:

[project]/src/main/resources/META-INF/MANIFEST.MF. The developer needs to update it according to the project requirements, specially to identify which Java packages are imported and exported, and the XML declarative file/s associated to the project.

Manifest-Version: 1.0
Bundle-ManifestVersion: 2
Bundle-Name: The [project] bundle of the MUSIC middleware
Bundle-SymbolicName: org.istmusic.mw.[project]
Bundle-Version: 0.0.2
Import-Package: org.osgi.framework;version="1.3.0",
 org.osgi.service.component;version="1.0.0"
Export-Package: org.istmusic.mw.[project]
Service-Component: src/main/resources/OSGI-INF/[component].xml

[project]/src/main/resources/META-INF/MANIFEST.MF

This MANIFEST file is used by Maven to generate the deployment unit of the project. It is basically the same file than [project]/META-INF/MANIFEST.MF but the project information is automatically generated by using Maven variables, and fixing the paths to the files (typically the XML declarative files).

Manifest-Version: 1.0
Bundle-ManifestVersion: 2
Bundle-Name: The ${pom.artifactId} bundle of the MUSIC middleware
Bundle-SymbolicName: ${pom.artifactId}
Bundle-Version: ${pom.version}
Import-Package: org.osgi.framework;version="1.3.0",
 org.osgi.service.component;version="1.0.0"
Service-Component: OSGI-INF/[component].xml

NOTE: The replication of the MANIFEST file is a very unfortunate fact but we haven´t found any workaround to make compatible an OSGi project in Eclipse and Maven simultaneously. Eclipse requires that the MANIFEST file is placed in the [project]/META-INF/MANIFEST.MF path. It is a developer task to synchronize both MANIFEST files to avoid inconsistent behaviour.