1 Application environment

This documentation section contains this and that.

1.1 Framework and concepts

1.2 Frontend

1.3 Backend

1.1 Framework and concepts

Oskari is a framework for easily building multipurpose web mapping applications utilizing distributed Spatial Data Infrastructures like INSPIRE. Oskari includes a frontend, a backend and in the future also a service bus. The user interface is implemented in JavaScript and the server functionality in Java. Oskari enables controlled extensibility. The service platform is kept flexible: functionality can be added both to the user interface and the server, and the application libraries can be changed.

The picture below shows the components of Oskari.

Application = starting one or more bundles. Feature = not used anymore, functions Bundle = a component in Oskari application. A selection of Oskari classes which form a component that offers additional functionality for an application. A bundle can offer multiple implementations for a functionality which can then be divided into smaller packages for different application setups. Packages can be used to offer a multiple views for the same functionality for example search functionality as a small on-map textfield or a window-like UI (see Tile/Flyout) for the same functionality. Component = Class = Plugin = bundles can contain plugins. Module = Modules are components that can be registered to Oskari. Registering allows these components to for example send requests and receive events. Registering a module also calls the module init method. Usually modules start listening to events and register request handlers on start methods. stop method is called when the module is stopped but they usually aren't stopped.

1.2 Frontend

The user interface is a Javascript-based single-page app built by selecting a series of modules that provide features for an application. The modules provide a documented API for interaction and/or easy replacement for a new implementation of a feature. You can mix and match the modules or create new ones to customize the application for your needs.

Oskari UI is implemented as a collection of reusable bundles. Bundles are used as uniform containers to ship and share new functionality to the application setups. Additions to existing functionality are implemented as Plugins shipped within the bundles.

1.2.1 Frontend architecture

Oskari-loader is started up when the browser signals the DOM is ready. The loader is passed the Oskari application startup sequence and configuration as JSON. The startApplication() method is called on loader and the processing of the startup sequence is started. Bundles referenced in the startup sequence are loaded and started. One bundle must be a "creator bundle" which initiates Oskari core. After the core init - services and request handlers can be registered to the core by any bundle. Reference to the map module can be fetched from the core and any map plugins can be registered to it.

Oskari JavaScript framework

• Oskari-loader is started up when the browser signals the DOM is ready.
• The loader is passed the Oskari application startup sequence and configuration as JSON.
• The startApplication() method is called on loader and the processing of the startup sequence is started.
• Bundles referenced in the startup sequence are loaded and started.
• One bundle must be a "creator bundle" which initiates Oskari core.
• After the core init - services and request handlers can be registered to the core by any bundle.
• Reference to the map module can be fetched from the core and any map plugins can be registered to it.

Bundle functionality

• Bundles can provide a an interface for other bundles to request some operation through a request handler.
• A bundle can provide a request class and register a handler for the request in the Oskari core.
• Another bundle can then send the request which will be processed by the other bundle.
• Another way to communicate with other bundles is to send out an event through Oskari core.
• Any bundle registered as an eventlistener for the given event is then notified about the event.

1.2.2 Libraries and technologies

Oskari frontend uses the following libraries and technologies:

• OpenLayers (map component)
• jQuery (map tools)
• jQuery UI (UI)
• React (map tools)
• Ant Design (icons)
• CesiumJS
• Lo-Dash
• geostats.js
• D3.js

You can get a list of all the libraries with npm with for example by running: npx license-checker. Just to get summary of licenses you can add --summary after the command.

1.2.3 Source code and folder structure

You can find Oskari frontend source code in here.

Oskari frontend source code has the following folder structure: /applications - Definitions for application setups combining bundles into a specific application /bundles - Implementation files for extension bundles /packages - Definition files for extension bundles /resources - CSS styles/images for extension bundles /sources - Oskari core /libraries - jQuery plugins and other dependencies/libraries

The folder structure follows a pattern where the first folder under the base folder is a namespace folder. Oskari uses framework for the main bundles, but this is optional and you can separate your bundles to own namespace. The next folder in the structure is named bundle. This is just a convention and is not a functional requirement. The next folder is named after the .

1.3 Backend

Backend functionality of the platform is implemented as a Java servlet, which can also be extended to handle new functionality.

1.3.1 Backend architecture

Backend architecture can be divided into three layers: service layer, control layer and interface layer. Webapp for Oskari server is packaged as oskari-map.war in sample-server-extension.

It handles most of the server side functionality alone using GeoServer for user generated content (myplaces, userlayers, analysis). The webapp is extensible and can be compiled from oskari-server components and built on them to create your own geoportal/web mapping server.

The backend is layered as services, controls, interfaces (though only webapp-map uses this extensively at the moment).

Service layer Service modules should be common libraries usable in any application. The actual business logic for Oskari operations should be in these modules.

• service-base has some common helpers and domain classes which are used throughout Oskari backend
• service-permission is a generic authorization lib for deciding who gets to see/do what
• service-search is a generic search lib that can be extended by adding and registering search channels.
• service-map has most (maybe a bit too much) of the business logic for servicing the Oskari functionalities
• service-control defines the control/routing structures/interfaces for control-layer to build upon
• shared-test-resources has some common helpers/templates to help testing

Control layer Control modules build on top of the service layer.

• control-base is the basis for all control-modules and has most of the basic AJAX handlers needed by the Oskari frontend.
  • NOTE! control-base contains some very specific functionalities that should be separated into separate control-extensions (for example analysis and thematic maps support)
• control-myplaces has AJAX funtionality related to myplaces functionality.
• control-example has example implementations for AJAX functionalities required by Oskari but usually overridden by platform specific functionalities such as user and content management.
• content-resources has tools, templates and scripts for populating and upgrading the database

Functions:

• Handles AJAX requests made by Oskari frontend
• Parses request parameters for input values to be used on service invocations (ActionParameters is not )
• calls one or more services to do business logic
• format a response based on service response

Interface layer The interface-modules build on top of the control-modules. Basically an HTTP interface with reference implementations for:

• HTTP Servlet: oskari-server/servlet-map
• Webapp: sample-server-extension/webapp-map

Responsible for:

• Handling user sessions
• Generating an ActionParameters object based on incoming request abstracting/normalizing the request for control layer
• Forwarding the request to control layer

1.3.2 Libraries and technologies

Oskari backend uses the following libraries and technologies:

• HAProxy (proxy, load balancer)
• Apache (proxy, load balancer)
• Nginx (proxy, load balancer)
• F5 load balancer
• Jetty
• Tomcat
• GeoServer
• PostgreSQL (database)
• PostGIS (spatial database)

1.3.3 Source code and folder structure

You can find Oskari backend source code in here.

Oskari backend source code has the following folder structure:

The folder structure follows a pattern where the first folder under the base folder is a namespace folder. Oskari uses framework for the main bundles, but this is optional and you can separate your bundles to own namespace. The next folder in the structure is named bundle. This is just a convention and is not a functional requirement. The next folder is named after the .