VAS Add on - motown-io/motown GitHub Wiki

Responsibility

The VAS add-on is responsible for implementing the VAS (Value Added Services) specification. It can be used by third parties to 'add value' by using information about the charging station(s) in the Motown system. Via the VAS interface they can obtain information about the location, type and status of charging stations. The VAS interface also implements a push-mechanism. External parties can subscribe to get updates about the status of charging stations.

Flow

A third party uses the VAS SOAP interface to subscribe to the VAS service provided by the Motown installation. After subscribing the 'GetChargePointInfo' service can be used to obtain information about the charging stations. After subscribing Motown will also be sending charging station status updates to the 'deliveryAddress' given at subscribing. Motown will keep sending status updates until 'unsubscribe' has been called.

  • third pary uses VAS SOAP interface to subscribe
  • after subscribing 'GetChargePointInfo' can be called for charging station information
  • Motown will send status updates to the 'deliveryAddress' given at subscribing

Implementing a VAS subscriber

To be able to receive status updates from Motown the VAS subscriber service should be implemented. When subscribing to the Motown VAS interface, the address of the subscriber service must be given.

A sample 'subscribeRequest':

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:ns="urn://Vas/Cs/2010/12/">
  <soap:Header xmlns:wsa="http://www.w3.org/2005/08/addressing">
    <ns:subscriberIdentity>identity here</ns:subscriberIdentity>
    <wsa:Action>/Subscribe</wsa:Action>
    <wsa:MessageID>uuid:bacb6dbb-0a9b-40d5-822d-3ac4595c103c</wsa:MessageID>
  </soap:Header>
  <soap:Body>
    <ns:subscribeRequest>
      <ns:deliveryAddress>your service endpoint here</ns:deliveryAddress>
    </ns:subscribeRequest>
  </soap:Body>
</soap:Envelope>

Configuring the add-on

JPA

Make sure a JPA entity manager factory is running.

The JPA entities reside in package

  • io.motown.vas.viewmodel.persistence.entities.

The repositories reside in package

  • io.motown.vas.viewmodel.persistence.repostories.

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.vas.viewmodel.persistence.entities"/>
    <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.vas.viewmodel.persistence.repostories.ChargingStationRepository">
    <property name="entityManagerFactory" ref="entityManagerFactory" />
</bean>

<bean id="subscriptionRepository" class="io.motown.vas.viewmodel.persistence.repostories.SubscriptionRepository">
    <property name="entityManagerFactory" ref="entityManagerFactory" />
</bean>

Subscriber service

The subscriber service is called by the event handler to update all subscribers about a status change. It requires a ExecutorService to asynchronously update subscribers, so if a subscriber cannot be reached or throws an Exception when being called all other subscriptions are still updated. Besides that it requires a reference to the SubscriptionRepository and an implementation of the SubscriberClient interface to contact subscribers.

Spring sample:

<!-- executor service for pushing status changes to subscribers -->
<bean id="vasExecutorService" class="java.util.concurrent.Executors"
      factory-method="newCachedThreadPool"
      destroy-method="shutdownNow"/>

<!-- client which will be used to push status changes to subscribers -->
<bean id="vasSubscriberSoapClient" class="io.motown.vas.v10.soap.subscriber.VasSubscriberSoapClient">
    <property name="proxyFactory">
        <bean class="io.motown.vas.v10.soap.subscriber.VasSubscriberServiceProxyFactory"/>
    </property>
    <property name="publisherIdentity" value="${io.motown.vas.v10.soap.publisher.identity}"/>
</bean>

<bean id="subscriberService" class="io.motown.vas.viewmodel.VasSubscriberService">
    <!-- repository mentioned in earlier example -->
    <property name="subscriptionRepository" ref="subscriptionRepository"/>
    <property name="executorService" ref="vasExecutorService"/>
    <property name="subscriberClient" ref="vasSubscriberSoapClient"/>
</bean>

Event listener

The VasEventHandler handles all events to keep the state of the charging stations in its local database up to date. The status related events also trigger an update of all subscribers to the service.

Spring sample:

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

<bean class="io.motown.vas.viewmodel.VasEventHandler">
    <!-- repository mentioned in earlier example -->
    <property name="chargingStationRepository" ref="chargingStationRepository"/>
    <property name="configurationConversionService">
        <bean class="io.motown.vas.viewmodel.ConfigurationConversionService"/>
    </property>
    <!-- service mentioned in earlier example -->
    <property name="subscriberService" ref="subscriberService"/>
</bean>

Publisher service

The publisher service handles incoming requests to the Motown VAS interface. It requires references to the charging station and subscription repositories. Besides the repositories it requires a VasConversionService to translate charging stations from the repository to a representation the web service understands.

Spring sample:

<bean id="vasPublisherService" class="io.motown.vas.v10.soap.publisher.MotownVasPublisherService">
    <property name="vasConversionService">
        <bean class="io.motown.vas.v10.soap.VasConversionService"/>
    </property>
    <!-- repositories mentioned in earlier samples -->
    <property name="chargingStationRepository" ref="vasWebServicesChargingStationRepository"/>
    <property name="subscriptionRepository" ref="vasWebServicesSubscriptionRepository"/>
</bean>

<jaxws:endpoint implementor="#vasPublisherService"
                address="/vasPublisherService" />

Web.xml:

<servlet>
    <servlet-name>CXFServlet</servlet-name>
    <servlet-class>org.apache.cxf.transport.servlet.CXFServlet</servlet-class>
    <load-on-startup>1</load-on-startup>
    <async-supported>true</async-supported>
</servlet>

<servlet-mapping>
    <servlet-name>CXFServlet</servlet-name>
    <url-pattern>/services/*</url-pattern>
</servlet-mapping>

API

Once configured and running the VAS add-on exposes a web service to which third parties can connect to retrieve information about the location, type and status of charging stations. The WSDL that describes this service can be found here.

Add a custom footer
⚠️ **GitHub.com Fallback** ⚠️