#2257: applications and services docs

docs/source/simulation_components/system/applications/database_client.rst

@@ -2,37 +2,111 @@
 
     © Crown-owned copyright 2023, Defence Science and Technology Laboratory UK
 
+.. _DatabaseClient:
 
 DatabaseClient
-===============
+##############
 
-The DatabaseClient provides a client interface for connecting to the ``DatabaseService``.
+The ``DatabaseClient`` provides a client interface for connecting to the :ref:`DatabaseService`.
 
 Key features
-^^^^^^^^^^^^
+============
 
-- Connects to the ``DatabaseService`` via the ``SoftwareManager``.
+- Connects to the :ref:`DatabaseService` via the ``SoftwareManager``.
 - Handles connecting and disconnecting.
 - Executes SQL queries and retrieves result sets.
 
 Usage
-^^^^^
+=====
 
 - Initialise with server IP address and optional password.
-- Connect to the ``DatabaseService`` with ``connect``.
+- Connect to the :ref:`DatabaseService` with ``connect``.
 - Retrieve results in a dictionary.
 - Disconnect when finished.
 
 To create database backups:
 
-- Configure the backup server on the ``DatabaseService`` by providing the Backup server ``IPv4Address`` with ``configure_backup``
+- Configure the backup server on the :ref:`DatabaseService` by providing the Backup server ``IPv4Address`` with ``configure_backup``
 - Create a backup using ``backup_database``. This fails if the backup server is not configured.
 - Restore a backup using ``restore_backup``. By default, this uses the database created via ``backup_database``.
 
 Implementation
-^^^^^^^^^^^^^^
+==============
 
 - Leverages ``SoftwareManager`` for sending payloads over the network.
 - Connect and disconnect methods manage sessions.
 - Payloads serialised as dictionaries for transmission.
 - Extends base Application class.
+
+Examples
+========
+
+Python
+""""""
+
+.. code-block:: python
+
+    from ipaddress import IPv4Address
+
+    from primaite.simulator.network.hardware.node_operating_state import NodeOperatingState
+    from primaite.simulator.network.hardware.nodes.host.computer import Computer
+    from primaite.simulator.system.applications.database_client import DatabaseClient
+
+    client = Computer(
+        hostname="client",
+        ip_address="192.168.10.21",
+        subnet_mask="255.255.255.0",
+        default_gateway="192.168.10.1",
+        operating_state=NodeOperatingState.ON  # initialise the computer in an ON state
+    )
+
+    # install DatabaseClient
+    client.software_manager.install(DatabaseClient)
+
+    database_client: DatabaseClient = client.software_manager.software.get("DatabaseClient")
+
+    # Configure the DatabaseClient
+    database_client.configure(server_ip_address=IPv4Address("192.168.0.1"))  # address of the DatabaseService
+    database_client.run()
+
+
+Via Configuration
+"""""""""""""""""
+
+.. code-block:: yaml
+
+    simulation:
+        network:
+            nodes:
+                - ref: example_computer
+                hostname: example_computer
+                type: computer
+                ...
+                applications:
+                    - ref: database_client
+                    type: DatabaseClient
+                    options:
+                        db_server_ip: 192.168.0.1
+
+Configuration
+=============
+
+.. include:: ../common/common_configuration.rst
+
+.. |SOFTWARE_NAME| replace:: DatabaseClient
+.. |SOFTWARE_NAME_BACKTICK| replace:: ``DatabaseClient``
+
+
+``db_server_ip``
+""""""""""""""""
+
+IP address of the :ref:`DatabaseService` that the ``DatabaseClient`` will connect to
+
+This must be a valid octet i.e. in the range of ``0.0.0.0`` and ``255.255.255.255``.
+
+``server_password``
+"""""""""""""""""""
+
+Optional. Default value is ``None``.
+
+The password that the ``DatabaseClient`` will use to access the :ref:`DatabaseService`.