Operator API Add on - motown-io/motown GitHub Wiki

Responsibility

The operator add-on is used by the operators to manage their charging stations.

Configuring the add-on

JPA

Make sure a JPA entity manager factory is running.

The JPA entities reside in package

  • io.motown.operatorapi.viewmodel.persistence.entities.

The repositories reside in package

  • io.motown.operatorapi.viewmodel.persistence.repositories.

As with all configuration samples, Spring is not required but it makes configuration a lot easier. A sample configuration of JPA in this add-on:

<!-- in-memory data source as a sample -->
<jdbc:embedded-database id="dataSource" type="HSQL"/>

<bean id="entityManagerFactory" class="org.springframework.orm.jpa.LocalContainerEntityManagerFactoryBean">
    <property name="dataSource" ref="dataSource"/>
    <property name="packagesToScan" value="io.motown.operatorapi.viewmodel.persistence"/>
    <property name="jpaVendorAdapter">
        <bean class="org.springframework.orm.jpa.vendor.HibernateJpaVendorAdapter">
            <property name="database" value="HSQL"/>
            <property name="generateDdl" value="true"/>
        </bean>
    </property>
</bean>

<!-- the repository beans can be used for setter injection on the domain service -->
<bean id="chargingStationRepository" class="io.motown.operatorapi.viewmodel.persistence.repositories.ChargingStationRepository">
    <property name="entityManagerFactory" ref="entityManagerFactory"/>
</bean>

<bean id="transactionRepository" class="io.motown.operatorapi.viewmodel.persistence.repositories.TransactionRepository">
    <property name="entityManagerFactory" ref="entityManagerFactory"/>
</bean>

Domain service

The operator api service contains the logic for accessing the repositories. The class is: io.motown.operatorapi.json.queries.OperatorApiService. The charging station and transaction repository should be injected into the operator api service.

Sample configuration:

<bean id="operatorApiService" class="io.motown.operatorapi.json.queries.OperatorApiService">
    <!-- repositories mentioned in other sample -->
    <property name="repository" ref="chargingStationRepository"/>
    <property name="transactionRepository" ref="transactionRepository"/>
</bean>

Event listener

The add-on listens to all events on transactions or charging stations. But it only does that if the event listeners are active and configured. The event listeners classes are io.motown.operatorapi.viewmodel.TransactionEventListener and io.motown.operatorapi.viewmodel.ChargingStationEventListener and requires access to a command gateway.

A sample configuration is:

<!-- make sure Axon picks up the EventHandler -->
<axon:annotation-config/>

<bean id="jsonCommandService" class="io.motown.operatorapi.json.commands.JsonCommandService">
    <!-- the gson which is used to convert the JSON to POJO's -->
    <property name="gson" ref="operatorApiGson"/>
    <!-- a list of json command handlers that fire commands based on the JSON sent to the API. -->
    <property name="jsonCommandHandlers" ref="jsonCommandHandlers"/>
    <!-- add-on id is a string value which is used to identify an add-on once multiple add-ons of the same type are running -->
    <property name="addOnId" value="1"/>
</bean>

JSON command handlers

The JSON command service has a reference to all the JSON command handlers in the Spring configuration. The JSON commands are (each command having its own handler in the io.motown.operatorapi.json.commands package):

  • AcceptChargingStation -> io.motown.operatorapi.json.commands.AcceptChargingStationJsonCommandHandler
  • AddChargingStationOpeningTimes
  • GrantPermission
  • ImproveChargingStationLocation
  • MoveChargingStation
  • PlaceChargingStation
  • RequestAuthorizationListVersion
  • RequestCancelReservation
  • RequestChangeAvailability
  • RequestChangeConfigurationItem
  • RequestClearCache
  • RequestConfigurationItems
  • RequestDataTransfer
  • RequestDiagnostics
  • RequestFirmwareUpdate
  • RequestReserveNow
  • RequestResetChargingStation
  • RequestSendAuthorizationList
  • RequestStartTransaction
  • RequestStopTransaction
  • RequestUnlockEvse
  • RevokePermission
  • SetChargingStationOpeningTimes
  • UpdateChargingStationReservable

The AcceptChargingStation has a reference (userIdentitiesWithAllPermissions) to a bean of type java.util.HashSet. This bean containts the usernames of the users who are allowed to create a charging station (currently only root). This bean is configured as follows:

<bean id="userIdentitiesWithAllPermissions" class="java.util.HashSet">
    <constructor-arg>
        <set>
            <bean class="io.motown.domain.api.security.SimpleUserIdentity">
                <constructor-arg name="identity" value="root" />
            </bean>
        </set>
    </constructor-arg>
</bean>

API

The add-on comes with a JSON REST API. The API can be used to sent commands to the command bus as JSON or get all the charging stations or transactions. The JSON REST API consists of 2 resources the provide access to the transactions and charging stations, they are located in package: io.motown.operatorapi.json.restapi.

A more detailed description of the API can be found here.

Sample Spring configuration:

<bean class="io.motown.operatorapi.json.restapi.ChargingStationResource">
    <property name="commandService" ref="jsonCommandService"/>
    <property name="service" ref="operatorApiService"/>
</bean>

<bean class="io.motown.operatorapi.json.restapi.TransactionResource">
    <property name="service" ref="operatorApiService"/>
</bean>

Sample web.xml configuration using Jersey:

<servlet>
    <servlet-name>JerseyOperatorApiServlet</servlet-name>
    <servlet-class>com.sun.jersey.spi.spring.container.servlet.SpringServlet</servlet-class>
    <load-on-startup>1</load-on-startup>
    <init-param>
        <param-name>com.sun.jersey.config.property.packages</param-name>
        <param-value>io.motown.operatorapi.json.restapi</param-value>
    </init-param>
    <init-param>
        <param-name>com.sun.jersey.api.json.POJOMappingFeature</param-name>
        <param-value>true</param-value>
    </init-param>
</servlet>

<servlet-mapping>
    <servlet-name>JerseyOperatorApiServlet</servlet-name>
    <url-pattern>/rest/operator-api/*</url-pattern>
</servlet-mapping>
Add a custom footer
⚠️ **GitHub.com Fallback** ⚠️