Dependency Management and Class Loading - rwth-acis/las2peer-template-project GitHub Wiki

las2peer allows to run multiple services using different library versions each. This allows dynamic service plugging and unplugging in future. To make use of this feature, service developers have to regard a few points.

Library management in las2peer

las2peer differs between two types of libraries: Platform libraries (Java, las2peer Core, WebConnector, REST-Mapper and dependencies) and service bundles. A service bundle manages classes and dependencies of one service.

To make service bundles 100% compatible with the core, classes are first loaded from the platform libraries (contained in the lib folder). If this fails, las2peer loads classes from a Repository (which is currently a file system repository using the service folder). The service dev should place all service packages and dependencies in the Repository.

Service classes are always overridden by the Platform. As consequence, make sure that no service class is contained in the platform's classpath as this will bypass las2peer's class loading mechanism.

Please note that service bundles are completely isolated from each other. A service cannot access another service bundle's class. In particular static classes cannot be shared between bundles, because each bundle loads each class using the bundle's class loader. Service-to-service communication can only be realized using Remote Method Invocation.

Maintaining the file system repository

All service dependencies which are not contained in the core should be places into the "service" folder following this naming scheme:

libraryName-major.minor.sub-build

Services should follow the scheme

service.package-major.minor.sub-build

Where minor, sub and build are optional.

Configuring the build script

The Template Projects build script puts the platform into the lib folder and additional service dependencies into the service folder. To add new service deps, open the etc/ivy/ivy.xml and add a dependency as follows:

<dependency org="org.apache.commons" name="commons-dbcp2" rev="2.0" conf="bundle->default" />

Each dependency having bundle->default as configuration attribute will be downloaded into the service folder; also its dependencies configured for the default configuration will be downloaded into the same directory as well.

Defining dependencies for las2peer

las2peer automatically resolves the service's dependencies and resolves them. To make use of this mechanism, you need to define these dependencies in your jar-file.

In the etc/ant_configuration/service.properties file dependencies are defined as follows:

service.dependencies=libraryName1;version="libraryVersion", libraryName2;version="libraryVersion", libraryName3;version="libraryVersion";resolution:="optional"

Where libraryVersion specifies a range of compatible versions, specified as follows:

  • major.minor.sub-build (e.g.: 1.0): an exact version
  • [major.minor.sub-build,major.minor.sub-build] (e.g.: [1.0,2.0]): any version v matching 1.0 <= v <= 2.0
  • [1.0,2.0): any version v matching 1.0 <= v < 2.0
  • (1.0,2.0]: any version v matching 1.0 < v <= 2.0
  • (1.0,2.0): any version v matching 1.0 < v < 2.0

Note that resolution:="optional" as shown for libraryName3 indicates that the library doesn't need to be loaded in order to start the service. In this case, the service needs to check if the library is available (catch ClassNotFoundExceptions).

This information will be added to the jar's Manifest file.

On service start, las2peer will automatically look for these dependencies on service start. If a dependency cannot be resolved (unless it's optional), the service will not be started. Note that libraries in the service folder (unlike the ones in the lib folder) are not automatically available to services.

Adding dependencies in Eclipse

After running ant get_deps, refresh your project in Eclipse and go to the lib/service folder right click on a library and choose Build Path -> Add to Build Path. Only add the platform and service dependencies here, do not add other services!

Checklist

  • Always put your service jars in the service folder.

There are two ways:

Debug and Production (recommended):

  • Place all dependencies that are not part of the las2peer platform into the service folder. Make sure that these dependencies are not contained in the lib folder. The easiest way is to use the Template Project's build script as described above.
  • Add dependency information to your service jar. Follow the guide shown above.

Debugging only (not recommended!):

  • For debugging purposes, you can place your libraries and service jars in the lib folder. This will bypass las2peer's class loading.
  • In order to start a service, the service jar needs also be located in the service folder.