Using a Service

1. Introduction

This tutorial introduces Services as a powerful way to allow one Component Instance to make use of functionality provided by another.

In this tutorial, you will:

  • Learn about the conceptual background to Services.

  • Create a Component Type which accesses a filesystem via Service Operations.

  • Learn how to make Service connections between Component Instances in Deployment Types.

2. Before You Begin

Guidance on the styles and conventions used in these tutorials is available here.

Unless otherwise directed, all commands in this tutorial must be run in the developing_components/UsingAService workspace.

You must have Groundkit installed as described in the Getting Started Guide.

Install a copy of the tutorials locally by running hgk-prepare-tutorials.

Navigate to the developing_components/UsingAService workspace in a terminal and run hgk workspace prepare to ensure it is ready to use.

3. Introducing Services

3.1. Contracts

In earlier tutorials you learned that Component Types are how we encapsulate functionality for reuse in Groundkit.

In order to use Component Types to build more complex systems they need to be connected together. A Component Instance which encodes data for uplink, for example, needs to be connected to a Component Instance for transmitting data via TCP.

Services are the primary means of making these connections between Component Instances in Groundkit.

A Service is a contract between Component Types. A Component Type can promise to fulfil the obligations of the Service. It can also state that it wants access to a Service to use the functionality it represents.

In this way Component Instances can be reliably connected together, regardless of when and by whom their corresponding Component Types were developed.

Thinking of Services in contractual terms is useful because it allows you to ignore the other characteristics of the Component Instances involved. For the purposes of connecting Component Instances together with Services, all that matters is that the relevant Component Types provide or consume the right Service.

3.2. Usage Patterns

Groundkit provides three kinds of Services for making these contractual connections between Component Instances.

  • Publish-Subscribe Services, in which a Publisher Publishes a Message for eventual use by any number of Subscribers. The EDS Service you met in the Hello World 3 tutorial falls into this category.

  • Send-Notify Services, in which a layer in a communication stack can send packet data to a lower layer and can notify a higher level of a stack when receiving data.

  • Request-Response Services, in which a Consumer issues an Operation to which a Provider must respond. This tutorial focuses on this kind of Service.

While some details are specific to Groundkit, the above usage patterns are very similar to those found in RPC and messaging frameworks. One widely available example of such a framework is ZeroMQ.

A Request-Response Service's contract consists of the Operations it defines.

A Component Type which Provides a Request-Response Service must do whatever is required to implement the Operations in the Service. It must handle requests from a connected Component Instance in line with the definition of the Service.

Conversely, a Component Type which Consumes a Request-Response Service is stating that, when instantiated, it must be connected to a Provider of that Service. The Component Implementation can assume this will be true.

3.3. Services in Groundkit

There are many examples of Provision and Consumption of Request-Response Services in Groundkit's library:

  • Access to Parameters is provided by the Parameter Access Service (PAS). It defines Operations like getScalarValue and setScalarValue. Any Component Type with at least one Parameter automatically Provides this Service.

  • Access to files and directories on filesystems is represented by the File Store Service (FSS). It defines Operations like openFile and readFile. Component Types which give access to a filesystem Provide FSS, while those which need to read and write file data Consume it.

You will learn more about this final example now.

3.4. The File Store Service

FSS is a Service consisting of Operations for accessing file systems. It is modelled after the POSIX file API.

The contract which a given Service defines is captured in the model in the form of a service.xml file. hgk can use the Service definition to produce human-readable Service documentation.

Generate the FSS Service documentation by running the following command:

hgk service generate-docs storage.FSS

Open the documentation generated under output.

As discussed above, a Service represents a contract between two Component Types. An important difference between Services and other kinds of API is that a Service is defined independently of either of the Component Types which make use of it.

Indeed, a single Service can be used as the contract between many different pairs of Component Types.

FSS defines many Operations, including those for opening files, writing to them, reading from them, and manipulating the directory structure of a filesystem.

A Provider of FSS must implement these Operations, while a Consumer may issue any of the Operations on offer, as long as it follows the rules given in the FSS service.xml.

Groundkit comes with the storage.fss.LocalFilestore FSS Provider, which you will be using later on.

In the next section you will see these concepts in action by creating an FSS Consumer and connecting it to a storage.fss.LocalFilestore Component Instance.

4. Implementing a Consumer

Typically, you will need to implement Service Consumers more often than Providers. The strict definition of Services means you can usually make use of pre-existing Service Providers to meet the needs of new Service Consumers.

In this section you’ll work on a storage.ConfigStore Component Type which emulates some features you might expect a real configuration store subsystem to have.

Once this is done, you’ll test it by instantiating it within a Deployment Type, and connecting it to a storage.fss.LocalFilestore Component Instance.

4.1. The storage.ConfigStore Component Type

Open the storage.SimpleConfigStore componentType.xml found here:

library/componenttypes/storage/simpleconfigstore/src/main/resources/com/brightascension/componenttypes/storage/simpleconfigstore/componentType.xml

As you can see, the Component Type already defines the interface the operator will use by Providing the storage.SimpleConfigStore Service.

Open the storage.SimpleConfigStore service.xml found here:

library/services/storage/simpleconfigstore/src/main/resources/com/brightascension/services/storage/simpleconfigstore/service.xml

The Service Provides two Operations:

  • A store Operation for storing and updating configuration values.

  • A get Operation for retrieving configuration values.

You will be updating these Operations to store the configuration values on the file system, rather than in memory.

4.2. Adding an FSS Requirement

At the moment storage.SimpleConfigStore stores configuration values in memory. We’d prefer if these were persisted on the file system.

To make use of FSS, you need to make storage.SimpleConfigStore an FSS Consumer. This is achieved by adding a <Services><Required><Service> element to its componentType.xml.

Add the <Required> element within the '<Services>' block:

           </Description>
         </Service>
       </Provided>
+      <Required>
+        <Service name="filestore" type="storage.FSS">
+          <Description>
+            The service to use for storing the configuration settings.
+          </Description>
+        </Service>
+      </Required>
     </Services>
     <!-- Tasks -->
     <!-- Actions -->

As usual, this addition to the componentType.xml requires the Component Type to be generated.

Generate the Component Type.

If you are not comfortable using hgk to generate Component Types, you can revisit earlier tutorials to refresh your memory.

4.3. Updating SimpleConfigStoreImpl.java

Since you have added an FSS Consumption to the SimpleConfigStore Component Type and generated it, several new files will have appeared.

The key file for issuing FSS Operations is StorageFSSFilestore.java. This file will have been generated at the following path:

library/componenttypes/storage/simpleconfigstore/src/main/java/com/brightascension/componentimpls/storage/simpleconfigstore/simpleconfigstoreimpl/include/container/storage/fss/StorageFSSFilestore.java

This file contains the methods which the SimpleConfigStore implementation must call to issue FSS Operations. The methods in this file can be accessed via a convenience function in the SimpleConfigStoreImpl.java.template file created by regenerating the Component:

New convenience method in SimpleConfigStoreImpl.java.template
  private StorageFSSFilestore storageFSSFilestore() {
    return container.storageFSSFilestore();
  }

Each Component Type which requires a given Service type calls its own methods to issue Service Operations.

This is in contrast to a typical API, where all clients of an API make the same calls.

Copy the new convenience method from the template into the Component Implementation.

@@ -4,6 +4,7 @@
  */
 package com.brightascension.componentimpls.storage.simpleconfigstore.simpleconfigstoreimpl;
 
+import com.brightascension.componentimpls.storage.simpleconfigstore.simpleconfigstoreimpl.include.container.storage.fss.StorageFSSFilestore;
 import com.brightascension.services.storage.simpleconfigstore.StorageSimpleConfigStoreGetResponse;
 import com.brightascension.componentimpls.storage.simpleconfigstore.simpleconfigstoreimpl.include.container.SimpleConfigStoreImplInterface;
 import com.brightascension.componentimpls.storage.simpleconfigstore.simpleconfigstoreimpl.include.container.SimpleConfigStoreImplContainer;
@@ -68,6 +69,10 @@ public class SimpleConfigStoreImpl implements SimpleConfigStoreImplInterface {
     return new StorageSimpleConfigStoreGetResponse(inMemoryStore.get(key));
   }
 
+  private StorageFSSFilestore storageFSSFilestore() {
+    return container.storageFSSFilestore();
+  }
+
   @Override
   public String toString() {
     return String.format("%s - %d", instanceName, id);

Now that your Component Implementation can issue FSS Operations, it’s time to use them to update the store and get Operations. You can consult the FSS documentation you generated earlier, but we can jump straight in as follows:

  • The store Operation must first open a file based on the key parameter, creating the file if it does not already exist. The FSS openFile Operation can achieve this.

  • It then needs to write the value to the open file. The writeFile Operation can achieve this.

  • The file needs to be closed, regardless of any failures in processing the data. The FSS closeFile Operation can be used for this.

Similarly, the get Operation must be updated as follows:

  • It must first open the file. If it doesn’t exist, it should return the empty string.

  • It should then read the data, parsing it as a String.

  • Finally, as before, the file needs to be closed, regardless of any errors in processing.

If you are confident working from this outline, you can try and update the Operations yourself. If not, we will cover each of the above steps in more detail now.

4.4. Updating store

In the store Operation implementation, you will now add a call to StorageFSSFilestore.openFile. Much like a POSIX fopen() call, this method takes a path to a file and returns a file handle to you.

In Groundkit, Service Operations can use Selection Identifiers to reference the resources they use. FSS Operations use Selection Identifiers as file handles.

In the store Operation implementation, add a call to StorageFSSFilestore.openFile. Remember, you can access StorageFSSFilestore via the convenience method you added aboves.

Show the added call to StorageFSSFilestore.openFile()
@@ -5,6 +5,8 @@
 package com.brightascension.componentimpls.storage.simpleconfigstore.simpleconfigstoreimpl;
 
 import com.brightascension.componentimpls.storage.simpleconfigstore.simpleconfigstoreimpl.include.container.storage.fss.StorageFSSFilestore;
+import com.brightascension.genone.exception.GenOneBaseException;
+import com.brightascension.services.storage.fss.types.FSSAccessMode;
 import com.brightascension.services.storage.simpleconfigstore.StorageSimpleConfigStoreGetResponse;
 import com.brightascension.componentimpls.storage.simpleconfigstore.simpleconfigstoreimpl.include.container.SimpleConfigStoreImplInterface;
 import com.brightascension.componentimpls.storage.simpleconfigstore.simpleconfigstoreimpl.include.container.SimpleConfigStoreImplContainer;
@@ -55,7 +57,15 @@ public class SimpleConfigStoreImpl implements SimpleConfigStoreImplInterface {
    */
   @Override
   public void storageSimpleConfigStoreConfigServiceStore(String key, String value) {
-    inMemoryStore.put(key, value);
+    try {
+      int file = storageFSSFilestore()
+          .openFile(key, true, false, FSSAccessMode.READ_WRITE)
+          .selectionId();
+    } catch (GenOneBaseException e) {
+      // Rethrow errors
+    } finally {
+      // Close the file
+    }
   }
 
   /**

Next, add a call to StorageFSSFilestore.writeFile to write the value to the file system.

Note, we haven’t enforced the max lengths of either the key or value defined in the SimpleConfigStore service.xml. You can choose to do that here if you like. For simplicity, we’ll skip it.

Show the added call to StorageFSSFilestore.writeFile()
@@ -6,6 +6,7 @@ package com.brightascension.componentimpls.storage.simpleconfigstore.simpleconfi
 
 import com.brightascension.componentimpls.storage.simpleconfigstore.simpleconfigstoreimpl.include.container.storage.fss.StorageFSSFilestore;
 import com.brightascension.genone.exception.GenOneBaseException;
+import com.brightascension.genone.util.SerialisationUtils;
 import com.brightascension.services.storage.fss.types.FSSAccessMode;
 import com.brightascension.services.storage.simpleconfigstore.StorageSimpleConfigStoreGetResponse;
 import com.brightascension.componentimpls.storage.simpleconfigstore.simpleconfigstoreimpl.include.container.SimpleConfigStoreImplInterface;
@@ -61,6 +62,9 @@ public class SimpleConfigStoreImpl implements SimpleConfigStoreImplInterface {
       int file = storageFSSFilestore()
           .openFile(key, true, false, FSSAccessMode.READ_WRITE)
           .selectionId();
+
+      storageFSSFilestore()
+          .writeFile(file, SerialisationUtils.getBytesForFixedString(value));
     } catch (GenOneBaseException e) {
       // Rethrow errors
     } finally {

We need to fulfill the storage.SimpleConfigStore Service contract by throwing a ConfigurationError if we encounter a problem. A SimpleConfigStoreConfigurationErrorException.java file has been generated by the Groundkit Tooling for this purpose.

Wrap the FSS exception and rethrow
@@ -11,6 +11,7 @@ import com.brightascension.services.storage.fss.types.FSSAccessMode;
 import com.brightascension.services.storage.simpleconfigstore.StorageSimpleConfigStoreGetResponse;
 import com.brightascension.componentimpls.storage.simpleconfigstore.simpleconfigstoreimpl.include.container.SimpleConfigStoreImplInterface;
 import com.brightascension.componentimpls.storage.simpleconfigstore.simpleconfigstoreimpl.include.container.SimpleConfigStoreImplContainer;
+import com.brightascension.services.storage.simpleconfigstore.exceptions.SimpleConfigStoreConfigurationErrorException;
 import java.util.concurrent.ConcurrentHashMap;
 
 /**
@@ -57,7 +58,7 @@ public class SimpleConfigStoreImpl implements SimpleConfigStoreImplInterface {
    * @param value the value to store
    */
   @Override
-  public void storageSimpleConfigStoreConfigServiceStore(String key, String value) {
+  public void storageSimpleConfigStoreConfigServiceStore(String key, String value) throws GenOneBaseException {
     try {
       int file = storageFSSFilestore()
           .openFile(key, true, false, FSSAccessMode.READ_WRITE)
@@ -66,7 +67,7 @@ public class SimpleConfigStoreImpl implements SimpleConfigStoreImplInterface {
       storageFSSFilestore()
           .writeFile(file, SerialisationUtils.getBytesForFixedString(value));
     } catch (GenOneBaseException e) {
-      // Rethrow errors
+      throw new SimpleConfigStoreConfigurationErrorException(String.format("Error storing %s with value %s", key, value), e);
     } finally {
       // Close the file
     }

Finally, add a call to StorageFSSFilestore.closeFile(). This must be called regardless of write errors.

Show the added call to StorageFSSFilestore.closeFile()
@@ -59,8 +59,9 @@ public class SimpleConfigStoreImpl implements SimpleConfigStoreImplInterface {
    */
   @Override
   public void storageSimpleConfigStoreConfigServiceStore(String key, String value) throws GenOneBaseException {
+    Integer file = null;
     try {
-      int file = storageFSSFilestore()
+      file = storageFSSFilestore()
           .openFile(key, true, false, FSSAccessMode.READ_WRITE)
           .selectionId();

@@ -69,7 +70,13 @@ public class SimpleConfigStoreImpl implements SimpleConfigStoreImplInterface {
     } catch (GenOneBaseException e) {
       throw new SimpleConfigStoreConfigurationErrorException(String.format("Error storing %s with value %s", key, value), e);
     } finally {
-      // Close the file
+      try {
+        if (file != null) {
+          storageFSSFilestore().closeFile(file);
+        }
+      }  catch (GenOneBaseException e) {
+        container.logError(String.format("Error closing file %s", key), e);
+      }
     }
   }

Once you’ve completed the above steps, the store Operation is fully implemented.

See if you can update the get Operation on your own!

Show the updated get Operation.
@@ -27,9 +27,6 @@ public class SimpleConfigStoreImpl implements SimpleConfigStoreImplInterface {
   // Container reference
   private final SimpleConfigStoreImplContainer container;
 
-  // An in memory config store
-  private final ConcurrentHashMap<String, String> inMemoryStore = new ConcurrentHashMap<>();
-
   /**
    * Constructor for SimpleConfigStore
    *
@@ -87,8 +84,29 @@ public class SimpleConfigStoreImpl implements SimpleConfigStoreImplInterface {
    * @return StorageSimpleConfigStoreGetResponse
    */
   @Override
-  public StorageSimpleConfigStoreGetResponse storageSimpleConfigStoreConfigServiceGet(String key) {
-    return new StorageSimpleConfigStoreGetResponse(inMemoryStore.get(key));
+  public StorageSimpleConfigStoreGetResponse storageSimpleConfigStoreConfigServiceGet(String key) throws GenOneBaseException {
+    Integer file = null;
+    try {
+      file = storageFSSFilestore()
+          .openFile(key, true, false, FSSAccessMode.READ_WRITE)
+          .selectionId();
+
+      byte[] value = storageFSSFilestore()
+          .readFile(file, Integer.MAX_VALUE)
+          .data();
+
+      return new StorageSimpleConfigStoreGetResponse(SerialisationUtils.deserialiseFixedString(value));
+    } catch (GenOneBaseException e) {
+      throw new SimpleConfigStoreConfigurationErrorException(String.format("Error retrieving %s", key), e);
+    } finally {
+      try {
+        if (file != null) {
+          storageFSSFilestore().closeFile(file);
+        }
+      } catch (GenOneBaseException e) {
+        container.logError(String.format("Error closing file %s", key), e);
+      }
+    }
   }
 
   private StorageFSSFilestore storageFSSFilestore() {

In the next section you will instantiate SimpleConfigStore in a Deployment Type within a Mission. This will allow you to test the get and store Operations.

5. The SimpleConfigStoreDemo Deployment Type

We have provided the SimpleConfigStoreDemo Deployment Type for you to use to test SimpleConfigStore. There is already a SimpleConfigStore Component Instance in the Deployment Type. The Deployment Type has been instantiated in the UsingAService Mission.

If, however, you try and generate or build the UsingAService Mission now, it will fail. This is because the new SimpleConfigStore.filestore Service Consumption you added has not been connected to an FSS Provider

5.1. Connecting filestore

Open the SimpleConfigStoreDemo deploymentType.xml and find the SimpleConfigStore Component Instance near the bottom.

To connect SimpleConfigStore.filestore to an FSS Provider, you must add a <Connections><Services><Service> element to the SimpleConfigStore Component Instance in SimpleConfigStoreDemo.

Add the following <Connections> element just below the SimpleConfigStore instance’s </Description> tag:

@@ -22,6 +22,11 @@
         <Description>
           An instance of the SimpleConfigStore component type
         </Description>
+        <Connections>
+          <Services>
+            <Service name="filestore" component="LocalFilestoreInst" service="fileSystem"/>
+          </Services>
+        </Connections>
       </Component>
 
       <!-- gRPC Server, provides gRPC access to gRPC Target Components -->

This connects the SimpleConfigStore Service Consumption specified by the name attribute to the Service Provision specified by the service attribute on the Component Instance specified by the component attribute.

In this case SimpleConfigStore.filestore will be fulfilled by storage.fss.LocalFilestore.fileSystem. The LocalFilestoreInst Component Instance has been initiated within the directory tmp. You can see this by opening LocalFilestoreInstInit.java.

5.2. Testing SimpleConfigStore

With SimpleConfigStore.filestore connected, the Component Instance is correctly set up and can now be tested:

To test SimpleConfigStore and its FSS Consumption, generate, build and run the Deployment Instance using the same approach as in previous tutorials:

hgk mission build UsingAService
java -jar output/missions/UsingAService/UsingAServiceTarget/UsingAServiceDeployment/UsingAServiceDeployment.jar

You should see the familiar message, Generating a mission-database for the mission UsingAService.

5.3. Sending Requests to the SimpleConfigStore

To enable gRPC requests to the SimpleConfigStore Service, the Component Type storage.SimpleConfigStoreTargetGRPC has been created and added to the Deployment for you. Future tutorials will cover how to create this Component yourself.

As before, a Bruno project has been provided for you at bruno/UsingAService.

Use the same approach as in the previous tutorial to open Bruno and load the collection provided at bruno/UsingAService:

  • Launch Bruno from the application menu.

  • Click the btn:[Open Collection] button and navigate to the collection and click the btn:[Open] button.

  • Select the config_get request under the UsingAService collection.

  • Select the refresh proto file methods button.

  • Click the btn:[→] right arrow button at the top of the request to send the request.

  • Since no /tmp/our.first.key file exists, the empty string will be returned as the value.

{
  "value": ""
}
  • Now try sending the config_store request. Once you have done so, you can resend the config_get request. This time you should see a non-empty value returned. If you inspect the /tmp/ directory, you should see a new file /tmp/our.first.key has been created.

{
  "value": "our.first.value"
}
❯ cat /tmp/our.first.key
our.first.value

Once you are happy to proceed, terminate the process in the terminal.

This tutorial has demonstrated using FSS to open and read files. The Service is also capable of writing files, creating directories, listing directory contents, and many other useful file system operations.

In later tutorials you will learn more about other Services defined in Groundkit.

6. Wrap Up

In this tutorial you have:

  • Learned about the concept of a Service in Groundkit.

  • Learned the difference between Request-Response Service Consumers and Providers.

  • Made use of the generated methods which grant Consumers access to their connected Providers.

  • Learned how to connect Consumers and Providers within a Deployment Type.

In the next tutorial you will learn about how unit testing is carried out in Groundkit. This will allow you to test and maintain your Component Types more efficiently than through the ad hoc approach you’ve been relying on so far.

Click here to move on to that now.