Gld Concepts: Difference between revisions

From NovaOrdis Knowledge Base
Jump to navigation Jump to search
 
(48 intermediate revisions by the same user not shown)
Line 1: Line 1:
=Internal=
=Internal=


* [[Gld User Manual#Concepts|gld User Manual]]
* [[Gld User Manual#Concepts|User Manual]]


=Load Driver Instance=
=Load Driver Instance=
Line 16: Line 16:


Store types: in-memory, hierarchical, etc. A fully qualified class name can also be specified - the corresponding key store will be instantiated if the implementation is found on the class path. Also see [[gld Configuration#Store_Configuration|store configuration]].
Store types: in-memory, hierarchical, etc. A fully qualified class name can also be specified - the corresponding key store will be instantiated if the implementation is found on the class path. Also see [[gld Configuration#Store_Configuration|store configuration]].
=Service=
The abstract representation of a target gld can send load to. A service is characterized by its [[#Service_Type|type]]. Services are instantiated and configured by the [[#Extension|extension support infrastructure]], and then passed to the [[#Load_Driver_Instance|load driver instances]] to be started and used.
==Service Type==
===Cache Services===
===JMS Services===
===HTTP Services===


=Extension=
=Extension=


An extension contains a specific Service implementation that delegates to actual service libraries. The extension name should be as close as possible to the original product nomenclature.  
A ''gld extension'' contains a specific [[#Service|Service]] implementation that delegates to actual third-party client or driver implementations. The Service implementation and associated classes contain implementation-specific details essential to connect to, and interact with the target service. As per gld 1.0, the Service implementation class must adhere to naming convention described here: [[Gld_Extension_Development#Service_Implementation_Class_Naming_Conventions|Service Implementation Class Naming Conventions]]. In the future, we plan to relax this requirement.
 
While it is possible for a gld deployment to host multiple extensions, it is uncommon, and somewhat error prone, as multiple client libraries get mixed on the same classpath. Usually, only one extension will be installed into a gld installation, as the load testing environment is target-specific.
 
==Service Instance Lifecycle==
 
The service is defined in the configuration file by declaring the [[#Extension_Name|name of the extension]] or its fully qualified class name. During the gld runtime initialization, the class is loaded, and the a Service instance is created via a no-argument constructor (see [https://github.com/NovaOrdis/gld/blob/master/core/api/src/main/java/io/novaordis/gld/api/service/ServiceFactory.java ServiceFactory]). Then, the service instance is configured with the content on the "implementation" section of the configuration file.


Examples:
==Extension Name==


jboss-datagrid (this is how JBoss DataGrid distributions are named)
The extension name, which is configured as "[[Gld_Configuration#Implementation_Name|service.implementation.name]]" in the gld configuration file, should be as close as possible to the original product nomenclature. For example, the extension providing a Service implementation for JBoss DataGrid is named "jboss-datagrid" (this is how JBoss DataGrid distributions are named)


It is possible to have several extensions for the same product, if the product introduces '''incompatible API changes''' between (usually) major versions. This is the case for JBoss DataGrid, so there is a jboss-datagrid-6 and a jboss-datagrid-7 extension. The corresponding extension JARs are jboss-datagrid-6-<extension-version>.jar and jboss-datagrid-7-<extension-version>.jar.
It is possible to have several extensions for the same product, if the product introduces ''incompatible API changes'' between (usually) major versions. This is the case for JBoss DataGrid, so there is a jboss-datagrid-6 and a jboss-datagrid-7 extension. The corresponding extension JARs are jboss-datagrid-6-<extension-version>.jar and jboss-datagrid-7-<extension-version>.jar.


In the rare cases where minor upgrades introduce incompatible API changes that renders a specific extension inoperable with that product version, a new extension can be released, and the name of the extension includes the name of the minor release of the product that introduced the incompatible API change. Hypothetical example: jboss-datagrid-7.5-<extension-version>.jar.
In the rare cases where minor upgrades introduce incompatible API changes that renders a specific extension inoperable with that product version, a new extension can be released, and the name of the extension includes the name of the minor release of the product that introduced the incompatible API change. Hypothetical example: jboss-datagrid-7.5-<extension-version>.jar.
Note that the extension name also shows up in the Maven Group ID of the corresponding extension project, with the exception that no target version information is present in the Group ID. The version information goes into the artifact ID, if necessary. For more details see:
{{Internal|Gld_Extension_Development#Maven_Coordinates|gld Extension Development - Maven Coordinates}}
For details on how to configure an extension, see the [[Gld_Configuration#Implementation_2|service implementation configuration]] section.
For details on how to implement a new extension, see the [[Gld_Extension_Development#Extension_Name|gld Extension Development]] article.


==Target Service Client Libraries==
==Target Service Client Libraries==


The GLD extension JAR does never embed product client libraries. gld can be configured to use the client libraries available in the operational environment (see "[[Gld_Configuration#Client_Libraries_Available_in_the_Operational_Environment|Configuring Client Libraries Available in the Operational Environment ]])" or those shipped with the gld distribution, as separate JARs, the way they were released by the vendor (see "[[Gld_Configuration#Client_Libraries_Shipped_with_the_gld_Distribution|Specifying Client Libraries Shipped with the gld Distribution]]").
The gld extension JAR never embeds third-party client/driver libraries. gld can be configured to use the client libraries available in the operational environment (see "[[Gld_Configuration#Client_Libraries_Available_in_the_Operational_Environment|Configuring Client Libraries Available in the Operational Environment ]])" or those shipped with the gld distribution, as separate JARs, the way they were released by the vendor (see "[[Gld_Configuration#Client_Libraries_Shipped_with_the_gld_Distribution|Specifying Client Libraries Shipped with the gld Distribution]]").


===Client Libraries Shipped with the gld Distribution===
===Client Libraries Shipped with the gld Distribution===
Line 37: Line 63:
<pre>
<pre>
$GLD_HOME
$GLD_HOME
        |
    |
        +--- extensions
    +- extensions
                        |
            |
                        +-- jboss-datagrid-7
            +- jboss-datagrid-7
                                     
                      |
                      +- jboss-datagrid-7-1.0.0.jar
                      |
                      +- 7.0.0
                            |                           
                            +- commons-pool-1.6.0.redhat-9.jar
                            +- infinispan-client-hotrod-8.3.0.Final-redhat-1.jar
                            +- infinispan-commons-8.3.0.Final-redhat-1.jar
                            +- infinispan-query-dsl-8.3.0.Final-redhat-1.jar
                            +- jboss-logging-3.3.0.Final-redhat-1.jar
                            +- jboss-marshalling-1.4.10.Final-redhat-3.jar
                            +- jboss-marshalling-river-1.4.10.Final-redhat-3.jar
</pre>


</pre>
==Extension Classpath==
 
All extensions and client libraries shipped with a gld installation are added to the ''extension class  path'', which is built dynamically by recursively looking up JARs available under the $GLD_HOME/extensions directory.
 
==Extension Development==
 
<blockquote style="background-color: #f9f9f9; border: solid thin lightgrey;">
:[[gld Extension Development]]
</blockquote>

Latest revision as of 23:07, 5 September 2017

Internal

Load Driver Instance

A load driver instance runs inside a Java virtual machine executing a control loop on the main thread.

Error Handling

The main LoadDriver loop is not supposed to throw any exception, all exception will be handled internally, and they will be logged at stderr or sent to the log file, depending on how the load driver logging is configured.

Store

The store is the ... used to save the key generated during a load run, so they can be accessed later. Most commonly, it is implemented as local file storage.

Store types: in-memory, hierarchical, etc. A fully qualified class name can also be specified - the corresponding key store will be instantiated if the implementation is found on the class path. Also see store configuration.

Service

The abstract representation of a target gld can send load to. A service is characterized by its type. Services are instantiated and configured by the extension support infrastructure, and then passed to the load driver instances to be started and used.

Service Type

Cache Services

JMS Services

HTTP Services

Extension

A gld extension contains a specific Service implementation that delegates to actual third-party client or driver implementations. The Service implementation and associated classes contain implementation-specific details essential to connect to, and interact with the target service. As per gld 1.0, the Service implementation class must adhere to naming convention described here: Service Implementation Class Naming Conventions. In the future, we plan to relax this requirement.

While it is possible for a gld deployment to host multiple extensions, it is uncommon, and somewhat error prone, as multiple client libraries get mixed on the same classpath. Usually, only one extension will be installed into a gld installation, as the load testing environment is target-specific.

Service Instance Lifecycle

The service is defined in the configuration file by declaring the name of the extension or its fully qualified class name. During the gld runtime initialization, the class is loaded, and the a Service instance is created via a no-argument constructor (see ServiceFactory). Then, the service instance is configured with the content on the "implementation" section of the configuration file.

Extension Name

The extension name, which is configured as "service.implementation.name" in the gld configuration file, should be as close as possible to the original product nomenclature. For example, the extension providing a Service implementation for JBoss DataGrid is named "jboss-datagrid" (this is how JBoss DataGrid distributions are named)

It is possible to have several extensions for the same product, if the product introduces incompatible API changes between (usually) major versions. This is the case for JBoss DataGrid, so there is a jboss-datagrid-6 and a jboss-datagrid-7 extension. The corresponding extension JARs are jboss-datagrid-6-<extension-version>.jar and jboss-datagrid-7-<extension-version>.jar.

In the rare cases where minor upgrades introduce incompatible API changes that renders a specific extension inoperable with that product version, a new extension can be released, and the name of the extension includes the name of the minor release of the product that introduced the incompatible API change. Hypothetical example: jboss-datagrid-7.5-<extension-version>.jar.

Note that the extension name also shows up in the Maven Group ID of the corresponding extension project, with the exception that no target version information is present in the Group ID. The version information goes into the artifact ID, if necessary. For more details see:

gld Extension Development - Maven Coordinates

For details on how to configure an extension, see the service implementation configuration section.

For details on how to implement a new extension, see the gld Extension Development article.

Target Service Client Libraries

The gld extension JAR never embeds third-party client/driver libraries. gld can be configured to use the client libraries available in the operational environment (see "Configuring Client Libraries Available in the Operational Environment )" or those shipped with the gld distribution, as separate JARs, the way they were released by the vendor (see "Specifying Client Libraries Shipped with the gld Distribution").

Client Libraries Shipped with the gld Distribution

$GLD_HOME
    |
    +- extensions
            |
            +- jboss-datagrid-7
                       |
                       +- jboss-datagrid-7-1.0.0.jar
                       |
                       +- 7.0.0
                            |                            
                            +- commons-pool-1.6.0.redhat-9.jar
                            +- infinispan-client-hotrod-8.3.0.Final-redhat-1.jar
                            +- infinispan-commons-8.3.0.Final-redhat-1.jar
                            +- infinispan-query-dsl-8.3.0.Final-redhat-1.jar
                            +- jboss-logging-3.3.0.Final-redhat-1.jar
                            +- jboss-marshalling-1.4.10.Final-redhat-3.jar
                            +- jboss-marshalling-river-1.4.10.Final-redhat-3.jar

Extension Classpath

All extensions and client libraries shipped with a gld installation are added to the extension class path, which is built dynamically by recursively looking up JARs available under the $GLD_HOME/extensions directory.

Extension Development

gld Extension Development