NEW (29.01.2024): We will change some dependency handling! For development with eclipse you must install the m2e PDE Integration into the Eclipse IDE.
- Help - Install New Software…
- Use the m2e Update Site: https://download.eclipse.org/technology/m2e/releases/latest/
- Select m2e PDE Integration
- Finish the installation
After the installation it can be used in the PDE Target Editor.
06.02.2024: Due to a bug in Eclipse, you will need to use the latest eclipse version (2024-03): https://www.eclipse.org/downloads/packages/release/2024-03/
Nearly everything in Odysseus is designed to be replaced or extended. Here are the typical ones:
- Language extensions
- Create a new language (not only for queries, could be a DSL for anything)
- Create a new Odysseus Script Commands (#....)
- Create a new Logical/PQL Operator
- Processing function extensions
- Create new datatypes
- Create new stream object types
- Data Handler
- Create a new wrapper
- Transport handler
- Protocol handler
- Create new functions for expressions and predicates
- Create new aggregation functions
- Create new operators
- Create new schedulers and scheduling strategies
- Create new meta data
Table of Contents
Some OSGi/Eclipse basics
- Bundles
- Aka plugin: An eclipse project
- Each bundle has its own class loader
- MANIFEST.MF: meta data for that bundle (name, version, imports, exports…)
- In Odysseus: a module that encapsulates functions
- Fragment
- A special bundle that will not exist allone but together with a host bundle
- Same class loader as host bundle
- Used to extend host bundle
- We do not use this anymore, better approach is declarative services
- Declarative Services
- OSGi way of dependency injection
- Defined by so called components
- Can provide functions by interfaces or use (bind/unbind) implementations by interfaces à examples later
- Feature: a feature is a collection of bundles
- Define a set of bundles, that belong together and builds some functionality (e.g. each wrapper has its own feature)
- An update site provides features
- A bundle can be part of many features
- Update-site:
- A collection of features that can be installed in Odysseus
- On the same way, as in Eclipse („Install new software“)
- Via command on ther server
- Via Odysseus-Script
- Product:
- A product is a runnable software (with an application)
- Can be defined by bundles or features
- We only use features to define products
OSGi Life Cycle
- Each bundle has a life cycle
- Installed: A bundle (with correct Metadata is installed)
- Resolved: All dependencies (MANIFEST) are found
- Uninstalled: removed from runtime
- Active: a bundle is activated
- E.g. call of bundle activator
- Remark: there is no need to start a bundle, if the bundle should only provide classes (as a library)
- Eclipse tries to resolve dependencies lazy, if this cannot be done, the bundle stays installed --> bundle cannot be used
OSGi debugging
TODO: Check commands with apache felix console
- When an application (product) gets started with –console (as in Odysseus always), there is a console available
- ss shows all currently available bundles and their current life cycle state
- Sometimes, there are problems because dependencies are missing (INSTALLED)
- Typical problem: The dependency defined in the MANIFEST.MF was not added to any feature
- diag <id> shows the missing dependencies
- Again: Resolved is no “problem” ;-)
- ls: shows all currently installed (declarative) services
- Unsatisfied: Some dependencies cannot be found
- Use comp <id> to determine missing dependencies
Setting up
...
This section describes how to set up Eclipse and Odysseus for developments.
1. Checkout
The current source code is availabe through SVN:
development.
New:
1. Prerequisites
You will need the following tools:
- Java 17 OpenJDK
- Eclipse for RCP and RAP Developers (Important! Do not use a standard eclipse version!)
- GIT client (you can use git from command line or with a tool of your choice)
2. Checkout Source Code
Remark: Under windows it is best to use a folder, that is not inside the user home path (because of long file names). A good option would be a base folder git somewhere on the root level.
There are different ways to create new functionality with Odysseus. The first way should be used if you want to add something new to Odysseus (e.g. a new wrapper) but do not want to change the common code base. This should be the preferred way of development with Odysseus:
Option 1: Extending Odysseus with New Plugins
Odysseus has a very large code base. To allow a lightweight start, we provide a template project in our Bitbucket server. You should clone or fork this project and use it to add new plugins to this template. The template can be found here: https://git.swl.informatikUser: lesend
Password: rurome48
URL: http://isdb1.offis.uni-oldenburg.de/projects/ODY/repos/odysseus/trunk/
Checkout the source-code. We suggest to checkout the whole trunk-folder outsice of / without Eclipse - e.g. with TortoiseSVN (http://tortoisesvn.net/) in Windows or via the command line tool (http://subversion.apache.org/). Alternativly, experts may also import all directly into eclipse using e.g. subclipse.
2. Setup Eclipse
We recommend to use a dedicated Eclipse (Eclipse for RCP and RAP Developers) for Odysseus with its own workspace, because there are some configurations that are predefined for a workspace location that is equal to the trunk folder. Therefore, if you firstly started eclipse, you have to choose the trunk folder as the workspace location. Thus, choose the same folder which you used for the checkout and contains subfolders like ac, core, cep etc.
...
odysseusrepotemplate/browse . When using git you should use the following command to clone Odysseus. The template contains some standard products and the target platform as a submodule. The "--recurse-submodules" flag clones this submodule when cloning the repository. Alternatively, you can clone the submodule individually.
| Code Block | ||
|---|---|---|
| ||
git clone --recurse-submodules https://git.swl.informatik.uni-oldenburg.de/scm/ody/odysseusrepotemplate.git newRepo
cd newRepo
cd odysseus_dev
git checkout master |
Remark: because you are not allowed to push updates to the template repository you should change your repository URL to your git location and rename your folder to your new repository name.
| Code Block | ||
|---|---|---|
| ||
// in your newRepo Folder!
git remote set-url origin <new url> |
ODT
There is also a first approach for an eclipse plugin that could make processing easier. For this, install the Odysseus Development Tools from the following update site
| Code Block |
|---|
https://odysseus.informatik.uni-oldenburg.de/download/odt/ |
and uncheck "Group items by category".
After installation and restart there is a new menu option Odysseus where you can create an initial project:
Option 2: Extending an Existing Odysseus Plugin/Extending Odysseus Core
You want to extend an existing plugin from Odysseus or extend the core system? Then, instead of cloning the empty template from Option 1, clone the repository of the plugin you want to develop on. If the plugin is hosted in our Bitbucket, you can probably find it in one of the projects in this list: https://git.swl.informatik.uni-oldenburg.de/projects . Look for example at the Odysseus, the Odysseus Incubation and Odysseus Wrapper projects. When you have found the repository you want to use, check it out and don't forget to clone the submodule to get the target platform definition and the standard products:
| Code Block | ||
|---|---|---|
| ||
git clone --recurse-submodules <your repo URL>
cd <repo>
cd odysseus_dev
git checkout master |
Remark: There could be some updates in odysseus_dev that is not already reflected in each module. So it is always a good idea to update the odysseus_dev submodule to the newest version.
If you missed the --recurse-submodules, you can also use:
| Code Block |
|---|
git clone <your repo URL>
cd <repo>
git submodule init
git submodule update
cd odysseus_dev
git checkout master
cd ..
|
3. Setup Eclipse
After Eclipse started, you have to import all bundles (these are the parts of odysseus Odysseus and are equal to a eclipse an Eclipse project). Use "File -> Import -> Existing Projects into Workspace" to import them into Eclipse as follows:
After clicking "Next", select all needed projects. In the follwing screenshot, only core (it is a subfolder) and its bundles are selected. Of couse, depending on the application, it is also possible to select other or even all projects. Each subfolder of trunk normally reflects a special feature, so you can either only import several subfolders/features or all available features if you use trunk as the "Select root directory". However, the core is a minimal set of needed bundles to run odysseus.
3. Target Platform
Since Odysseus has some dependencies to other external features like Eclipse GEF or the Equinox framework, it is recommended to use the target-platform definition.
.
Now there are many project already opened:
Most of them are from odysseus_dev.
The source code folder has the following subfolders:
- client: contains all bundles that run on the client and don't have any dependencies to the server directly. It mainly offers the GUI.
- common: this holds common stuff and utilities that are needed on both server and client. Common does not have any dependencies to other folders like server, client...
- monolithic: this folder contains bundles that will only work in a monolithic system where server and client are the same product
- resource: possibly some resources for the bundle, but probably empty. The resources are part of the target platform and are downloaded automatically by Eclipse when settings the target platform.
- server: this is the server part of Odysseus and contains Odysseus main functionalities. Except of common, it does not have any dependencies to other folders. It does not have any GUI or client functionalities.
- test: contains stuff for testing and benchmarking
4. Target Platform
You now see a lot of compiler error. This is because the target platform is not set.
The target platform can be found in the project targetplatform.
Choose the correct Targetplatform for you work.
Remark: It works best, when you first open the file (double click) and wait some time (until the platform is resolved).
Click "Set as Active Target PlatformThis definition is provided via the "target-platform.target" file and can be found in the bundle/project called "de.uniol.inf.is.odysseus.updatesite". Open this file and click "Set as target platofrm" to use this as your target platform. Notice, the target platform is valid for your whole workspace (therefore we recommend to use a dedicated workspace for Odysseus development).
If you use the test-features, you have to install testNG into your running platform. you have to do the following:
if you need testNG, this feature can be installed through "Help -> Install new Software". Afterwards enter the update site (http://beust.com/eclipse) into the work with field and hit enter.
Select the entry "TestNG" and click "Next" to install the feature. Maybe you have to restart Eclipse after the installation.
Important: Do not click, if "Resolving..." is still active!
After that, the project will be compiled and there should not be any errors anymore.
If there are still errors, you should try to update the odysseus_dev folder (sometimes there are errors with the sites, that dliver target platform contents)
5
...
. First Run - Available Products
Now , you should be able to run Odysseus. The bundle "de.uniol.inf.is.odysseus.rcp.starter" has There are some predefined product-definitions to run Odysseus. Depending on the bundles/folders you checked out before they can differ, but the standard submodule should contain three products:
- Odysseus Studio 2 (FileStore) - Runs Odysseus with an integrated GUI (called Studio). This configuration saves the state of Odysseus if it is terminated. E.g. all installed sources and queries are restored after Odysseus is restarted.
- Odysseus Studio 2 (MemoryStore) - This is similar to FileStore, but does not save the state. So, each time when Odysseus starts, it has an empty and fresh state.
- Odysseus Studio 2 Server (MemoryStoreServer - (located in de.uniol.inf.is.odysseus.server.product) - This is just a server-based instance of Odysseus (without any GUI) which can be configured among other things used e.g. via a webservice. It is a memory based version (see above). REST.
- Odysseus Studio 2 (Client) - (located in de.uniol.inf.is.odysseus.client.product) - This is only the client part (GUI) and it connects to the Odysseus Studio 2 Server via a webservice (thus, you need the server too!), which tries to connect to an Odysseus Server instance via webservice.
- Odysseus Studio 2 - (located in de.uniol.inf.is.odysseus.monolithic.product ) - This combines server and client into a single product and adds some additional bundles that only work in such a monolithic combination.
For your first runFor the first time, the easiest way is to start the "Odysseus Studio 2 (MemoryStore)"" (de.uniol.inf.is.odysseus.studio.product.monolithic). Open this file and go to the tab "Overview". Click "Synchronize" under "Testing" and afterwards click "Launch an Eclipse application" to run Odysseus (you can alternatively run it in debug mode if you want). When Odysseus Studio (the GUI) comes up, you have to insert some credentials. A default user is "System" and his the password is "manager", the tenant can be left empty. Now Odysseus should have been startedbe up and running.
5. Logging
Odysseus comes with the Simple Logging Facade for Java (SLF4J). To use logging add the de.uniol.inf.is.odysseus.slf4j bundle. In this bundle you can find the log4j.properties to configure the logging behaviour.
6. Additional Information
...
Features
Since Odysseus is an OSGi based application, it is devided divided into several bundles (the bunch of projects you checked out and imported before). To keep the overview of all bundles, they are combined to features. Each feature reflects a special functionality of Odysseus. thusThus, we have a core.feature that encapsulate encapsulates all minimal needed bundles or the studio.feature that contains all bundles for the RCP aka GUI (i.e., GUI) of Odysseus (what we call Odysseus Studio). The combination of several features is called a "product" - which should be runnable. The section above, for example, lists four three products that combine different sets of features.
The core feature is necessary , because it contains all fundamental functions for Odysseus. Here's a list of Odysseus Features: Features. See Adding features to products how to add a new Feature to an existing product.
...
Logging
Odysseus comes with the Simple Logging Facade for Java (SLF4J). To use logging, add the de.uniol.inf.is.odysseus.slf4j bundle. In this bundle you can find the log4j2.xml to configure the logging behavior (or use one of the given).