This chapter gives a more technical overview. It describes each layer of the platform by giving an overview of its packages and the code it contains. Furthermore it describes how a message proceeds through the platform. If you are planning on adding your own Domain Adapter or Protocol Adapter, it will be useful to read this chapter to get a feeling of how the Platform has been built.

A Request through the Platform

The picture below depicts an example of a request (OSLP SetLight request) proceeding through the platform to a device.

• A web request enters the platform at its EndPoint, which in turns calls the RequestService. The RequestService checks if the organisation in the request is authorized, creates the request message and sends it to the MessageSender which in turn puts it on the queue of the Domain Adapter.

• In the Domain Adapter, the incoming message is processed in the MessageProcessor, which in turn calls the Request Service. Here the message is converted to a DTO object. The CoreRequestMessageSender puts the message on the Core Queue.

• The MessageListener in Core receives the message. The DeviceRequestMessageService contains generic functionality such as Authorization, Validation, etc. Once these procedures are completed, the message is routed to the appropriate protocol adapter.

• In the Protocol Adapter the message is received by the MessageListener. It is processed through the MessageProcessor and OslpDeviceService. The request eventually ends up in the OslpChannelHandler, where the actual Protocol Request to the device is made.

For a detailed description of each layer, please take a look at a more detailed description of each layer in this chapter.

Configuration files

The Platform uses property files for certain settings (such as JMS settings, Persistence settings, etc.). These files are stored in property files which can be found in the Config repository on Github. These files are sym linked to /etc/osp/, where the Platform (through reference in context.xml) looks for the property files.

The Web Services layer contains the web services that are used to communicate with the Platform. The Open Source Smart Grid Platform uses the Simple Object Access Protocol or SOAP to expose its interfaces. The Web Services Adapter receives requests and sends those to the Domain Adapter. An incoming request is converted to a Domain Object, and put on the MessageQueue of the Domain layer. The Web Services layer also has a queue for incoming responses from the Domain adapter.

Each domain of the Platform has its own web services:

Generic

• Core - osgp-adapter-ws-core: Contains the Core (common) web services.

• Admin - osgp-adapter-ws-admin: Contains the Admin web services.

• Shared - osgp-adapter-ws-shared: Contains shared endpoints, such as header authorization

• Database - osgp-adapter-ws-db: Contains repositories for persistence.

Domain

• Public Lighting - osgp-adapter-ws-publiclighting: Contains the Public Lighting web services.

• Smart Metering - osgp-adapter-ws-smartmetering: Contains the Smart Metering web services.

• Tariff Swithcing - osgp-adapter-ws-tariffswitching: Contains the Tariff Switching web services.

• Microgrids - osgp-adapter-ws-microgrids: Contains the Micro Grids web services.

• Distribution Automation - osgp-adapter-ws-distributionautomation: Contains the Distribution Automation web services.

For a description of the WSDL's see the Domain Chapter.

General Package structure

A description of the general package structure of a web service component.

application

• config: Contains the configuration files for the Component. Uses the property files in /etc/osp/.

  -- ApplicationContext

  -- AdapterInitializer

  -- MessagingConfig

  -- PersistenceConfig

  -- WebServiceConfig

• exceptionhandling: Exceptions are defined here.

• mapping: Custom Orika converters.

• services: Contains services used by the domain, such as AdHocManagement. These are called by the end points and convert the request to a Domain Object and put the request on the domain message queue using the JMS classes.

endpoints

• EndPoints for the web services: contain a reference to a service that proceeds with handling the request.

infra

• jms: contains the JMS classes such as:

  -- MessageSender(s)

  -- MessageType

  -- ResponseMessageFinder

webapp

The WSDL and schema definitions can be found under main/webapp/WEB_INF/wsdl.

The Protocol Adapters are responsible for the actual communication to and from a device. They usually operate in a certain domain, and might use common/ generic functions from the platform.

The Open Smart Grid Platform currently has the following protocol adapters:

• Protocol-Adapter-DLMS: Smart Metering

• Protocol-Adapter-IEC61850: Public Lighting, Micro Grids and Distribution Automation

• Protocol-Adapter-OSLP: Public Lighting and Micro Grids

General package structure

application

• config: Contains the configuration files for the Component. Uses the property files in /etc/osp/.

  -- ApplicationContext

  -- MessagingConfig

  -- OsgpProtocolAdapterOslpInitializer

  -- OslpConfig

  -- OslpPersistenceConfig

• mapping: Custom Orika converters.

• services: Contains the (functional) services that control communication from (and to) the device. Also persists requests and responses, and deals with security. Actual communication is done through the classes in the infra package.

device

Contains the Protocol Adapter Objects used for the Protocol Adapter.

• requests: Objects representing the requests that are supported by this adapter.

• responses: Objects representing the responses that are supported by this adapter.

domain

• entities: Entities used for persistence.

• repositories: Repositories used for persistence.

exceptions

Contains the exceptions that might be thrown while communication with a device, e.g. ValidationException, MessageRejectedException, etc.

infra

This package contains all the code for communication through JMS (Platform) and Networking (Device).

• messaging: Contains the JMS Messages, MessageListeners, MessageSenders and MessageProcessors.

• networking: Contains the classes that are responsible for connecting to a device using a certain protocol.

services

Services used to check the request status.

The Domain Adapters are responsible for receiving requests from the Web Services layer, and delivering them to the Core layer. The Domain Layer mainly contains MessageProcessors and Services for request handling.

The Core/Admin components contains the shared functionality, while the Domain components contain additional domain specific functionality.

At the moment the Platform uses the following Domain Adapters:

Generic

• Core - osgp-adapter-domain-core: Contains Core (common) functionality; AdHocManagement, FirmwareManagement, etc.

• Admin - osgp-adapter-domain-admin: Contains Admin functionality, e.g. DeviceManagement.

Domain

• Public Lighting - osgp-adapter-domain-publiclighting: Contains functionality for the Public Lighting Domain.

• Smart Metering - osgp-adapter-domain-smartmetering: Contains functionality for the Smart Metering Domain.

• Tariff Switching - osgp-adapter-domain-tariffswitching: Contains functionality for the Tariff Switching Domain.

• Microgrids - osgp-adapter-domain-microgrids: Contains functionality for the Micro Grids domain.

• Distribution Automation - osgp-adapter-domain-distributionautomation: Contains functionality for the Distribution Automation domain.

General Package structure

application

• config: Contains the configuration files for the Component. Uses the property files in /etc/osp/.

  -- ApplicationContext

  -- DomainAdapterInitializer

  -- MessagingConfig

  -- PersistenceConfig

• mapping: Custom Orika converters for mapping to/from DomainObjects/DTO Objects.

• services: Contains most of the domain logic, related to the specific services of the adapter. The service classes converts DTO objects to Domain objects (or vice versa), and put the request on the Core queue through the JMS classes.

infra

• jms.core: Inbound/outbound messages from/to the Core layer.

  This package contains Messages, MessageListeners, MessageSenders and MessageProcessors for sending requests to the Core Queue, or receiving and processing responses from Core.

• jms.ws: Inbound/outbound messages from/to the web services layer.

  This package contains Messages, MessageListeners, MessageSenders and MessageProcessors for sending requests to the Web Services Queue, or receiving and processing responses from the web services layer.

The Core layer of the Open Source Grid Platform is responsible for Validation, Translation, Authorisation and Routing of request messages. It also contains all the Domain Objects.

The core layer consists of two components:

• osgp-domain-core: Shared Domain objects, services, repositories, etc. These classes are used through the entire platform.

• osgp-core: Logic for routing domain requests, scheduling, retrying, etc.

General Package structure: osgp-domain-core

• entities: Defines the entities used for persistence.

• exceptions: Domain specific exceptions reside here.

• repositories: Repositories that contain logic for persisting entities.

• services: Domain services that reference a repository.

• specifications: Interfaces that define specifications for Devices and Events.

• validations: Validators and constraints.

• valueobjects: Definitions of the Domain Objects.

General Package structure: osgp-core

application

• config: Contains the configuration files for the Component. Uses the property files in /etc/osp/.

  -- ApplicationContext

  -- OsgpCoreInitializer

  -- DomainMessagingConfig

  -- PersistenceConfig

  -- ProtocolMessagingConfig

  -- SchedulingConfig

• services: Services that process device requests/ responses. Checks for authorization, and if the request is supported by the platform, it will be routed to the appropriate protocol adapter.

• tasks: Contains task scheduler logic.

domain.model

These packages contain interfaces for the Services.

• domain: Interfaces for the Domain services.

• protocol: Interfaces for the Protocol services.

infra.jms

• domain: Contains Messages, MessageListeners and MessageProcessors for Domain related messaging.

• protocol: Contains Messages, MessageListeners and MessageProcessors for Protocol related messaging.

Platform

• Apache ActiveMQ: Open source messaging server, used to relay messages between components of the open smart grid platform. ActiveMQ is an open source message broker written in Java and a full Java Message Service (JMS) client. It provides "Enterprise Features" which in this case means fostering the communication from more than one client or server.

• Apache HTTP server: Web server, used as front for Apache Tomcat.

• Apache Tomcat: Provides a "pure Java" servlet container for Java code to run in.

• pgAdmin-III: PostgreSQL administration and management tools.

• Protobuf (Google Protocol Buffers): A language-neutral, platform-neutral, extensible way of serializing structured data for use in communications protocols, data storage, and more.

• Flyway: Agile database migration framework for Java

• HikariCP: JDBC connection pool

• Hibernate: Object/Relational mapping

• Netty: Network application framework for protocol servers & clients

• OpenMUC: Library implementing the IEC61850 and DLMS/COSEM communication standard

• Orika: Java bean mapping

• Spring: Application development framework. Several Spring libraries are used, including Spring Data, Spring Security and Spring WS.

• Puppet: Application for Automatically delivering, operating and securing your infrastructure

Development

• Bower: Package manager for Javascript packages. Web applications consist of various components; frameworks, libraries, assets, utilities, and rainbows. Bower manages all these things for you.

• Eclipse: IDE for developing software.

• FileZilla: FTP application.

• Git: Version control system.

• NodeJS: Tooling suite with various Javascript tools.

• NPM: Package manager for the NodeJS Javascript applications.

• Putty: A free and open-source terminal emulator, serial console and network file transfer application.

• Vim: Source code editor.

• Apache Maven: Software project management tool.

• GIT & GitHub: Source code management.

Testing &QA

• Apache JMeter: Application designed to load test functional behaviour and measure performance.

• Cucumber: automated acceptance testing framework.

• Gherkin: DSL for acceptence testing framework.

• Sonarqube: Quality management platform.

• SoapUI: Functional testing tool for testing web services.

• JUnit: Unit testing.

• Mockito: A Mock framework for Unit testing.

The following table presents an overview of the components and the most important technical choices per component.