Usage

Ekko Proxy has an easy and intuitive web client made by engineers for engineers.

Create a Ekko Proxy instance

To create a proxy click the Create Proxy navigation link. You should now see the Create Ekko Proxy page below where you can enter the proxy details to setup a new HTTP or JDBC based Ekko Proxy instance.

The fields on the HTTP Proxy Settings page are described below:

Field	Description
Import/Export settings	Click to select import / export option from menu: : Import Settings... Shows import settings dialog where Ekko Proxy settings files (EkkoProxySettings_*.json or a zip file containing one or more of the same) can be dragged & dropped or selected for import. : Export Settings Exports any Ekko Proxy settings files (EkkoProxySettings_*.json) to your browser downloads directory as a zip file. : Install License... Shows install license dialog where the Ekko Proxy license (ekkoproxyserver.lic) and certificate (ekkoproxyserver.der) files can be dragged & dropped or selected for installation.
Listener Https	Select to toggle the listener port between: : HTTP : HTTPS
Listening Port *	The port number [1 - 65535] that the Ekko Proxy should be listening on for incoming messages. Clients connect to this port on the host where Ekko Proxy server is hosted be it on a localhost computer or on a remote server. Note when the field gains focus a suggestions list of previously defined proxies will show, if any exist. Note when the field looses focus or when picking from the suggestions list, then previously saved settings will be automatically loaded, if any exist. Alternatively pressing enter will also load any saved settings and move focus to the 'CREATE PROXY' button where pressing enter again will create the Ekko Proxy instance. Lastly its also possible to drag & drop an existing proxy settings file (e.g. EkkoProxySettings_1080.json) on to this screen to fill in the fields.
Target Host *	The host / ip of the target server where the requests will forwarded to in passthrough or record mode. Note this should be the target host name or ip address without the protocol part i.e. without 'http://' or 'https://' as this is controlled by the 'Target Https' setting below.
Target Port *	The port number [1 - 65535] of the target server where the requests will forwarded to in passthrough or record mode.
Target Https	Select to toggle connecting to the target using: : HTTP : HTTPS
Certificate File	An SSL certificate can be specified if required for the target HTTPS connection. : Upload Certificate Shows upload SSL certificate dialog where a SSL certificate file can be drag & dropped or selected for upload.
Certificate Password	An SSL certificate password can be specified if required for the target SSL certificate.
Output Directory *	The directory to where the Ekko Proxy instance should store recordings. Can be a full path or relative. Note this field may be read-only if a fixed output directory has been specified on the command line when starting the Ekko Proxy server.
Description	An optional description of the proxy that will be displayed on the proxy view. If not set it will default to 'The Ekko Proxy service virtualization server is started|stopped'
Output Format	The output format to use when displaying requests and responses: Auto: Determines the formatting (Json or Xml) from the Content-Type header. Json: Always use Json formatting. None: Use no formatting. Xml: Always use Xml formatting.
Operation Mode	The operation mode of the Ekko Proxy instance. See Operation modes section for details.
Expression Format	The expression format to use in the 'Organising Recordings' and 'Normalise Recordings' tables: JsonPath: Use JsonPath expressions. Regex: Use regular expressions. XPath: Select to use XPath expressions when working with XML.
Send CORS headers	Tick this box if you want the proxy to automatically respond to HTTP OPTIONS requests and send CORS headers in all responses.
Organising Recordings	If you want to organise the recorded requests and responses into various sub-folders based on information in the requests, then you can specify XPath, JsonPath or Regular expressions here to select the information from the requests and use to create sub-folders under the output directory. Note the order of the expressions determine the order of the sub-folders. See Organising recordings for more details. : Adds a new row to the table. : Launches the Expressions test dialog. : Use request URI in output path. If selected, the request url will be part of the output folder path where the requests and responses are saved to. For example if the 'Output Directory' is set to C:\temp and a request is having a path of /foo/bar then the requests and responses for this web service will be saved in C:\temp\foo\bar.
Normalise Recordings	The filename key for a request and response pair is made up of hashed request information. There may be parts of the request that are unique per request e.g. a transaction id, session id or timestamp etc. which would prevent playback mode from working as the filename key would never be the same. To solve this you can specify XPath, JsonPath or Regular expressions here that will remove any matching fields in the request e.g. //ServiceRequest/SessionId before constructing the recorded filename key. Note when using XPath or JsonPath expressions you can only exclude request information from the request body. If you need to exclude information from the URI, query string or headers (if 'Include HTTP headers in filename key' option is selected) then please use Regular expressions instead. See Normalise recordings for more details. : Adds a new row to the table. : Launches the Expressions test dialog. : Include HTTP headers in filename key. If selected, the HTTP request headers are included in the key for the saved requests and responses. Note if there are request headers that vary per request for a service then you should either not use this option or use regular expressions in the 'Normalise Recordings' table to exclude them as otherwise playback would not work. : Save formatted content. If selected the saved recordings will be formatted according to the Output Format.
CREATE PROXY	Clicking the button (or pressing enter when focused) will create the new Ekko Proxy instance, provided there are no validation errors. Note you need a license to be able to create more than one proxy instance.

An example of a filled HTTP proxy settings screen can be found below:

Note you can also drag & drop an existing proxy settings file (e.g. EkkoProxySettings_1080.json) on to this screen to fill it in.

Note the number of concurrent Ekko Proxy instances that can be created is limited without a license.

Similarly a JDBC database proxy can be created by clicking on the JDBC Proxy tab as per below screenshot:

The fields (that differs from the HTTP proxy) on the JDBC Proxy Settings page are described below:

Field	Description
Secure Sockets	Toggles between Secure Sockets being on/off: : Secure Sockets Off : Secure Sockets On Note this is only applicable for when using RMI to communicate with the EkkoProxy JDBC proxy instance.
Connection Type	The connection type provides two options on how connections to the database are created: DriverManager: creates connections to a database via the DriverManager class using a database URL. A driver implementation class will have to be specified in the 'Driver Classname' field to use this way. DataSource: creates connections to a database via the DataSource class using given properties. A data source implementation class will have to be specified in the 'DataSource Classname' field to use this way. Note the DriverManager does not provide connection pooling out of the box but if the "ekkoproxy.jdbc.connectionPooling" setting (see installation) has been set connections will be pooled using Apache commons dbcp2.
Driver Classname *	If DriverManager is selected as the connection type then this field is displayed and needs to have the full classname of the JDBC database driver to be used for creating the connections e.g. 'oracle.jdbc.driver.OracleDriver'.
DataSource Classname *	If DataSource is selected as the connection type then this field is displayed and needs to have the full classname of the JDBC database datasource to be used for creating the connections e.g. 'oracle.jdbc.pool.OracleConnectionPoolDataSource'.
Username	The database username, if any.
Password	The database password, if any.
URL *	The URL of the database connect string e.g. jdbc:oracle:thin:@some.machine.test.group:1522/DB01.test.ekkoproxy.com Note this field is shown only if a DriverManager connection type is selected.
Verbosity Level	The verbosity level determines which JDBC commands triggers events to be fired and subsequently shown in Ekko Proxy: All: show all commands. Connections and Statements: shows commands for all connections and statements. Connections: show commands for connections only. Statements: show statement commands only. PreparedStatements: show prepared statements commands only. CallableStatements: show callable statements commands only.
Mock Path *	Sets the mock path for this proxy that's used as a HTTP equivalent request URL. This can then be used to define matching mock responses in the mock editor.
Driver Properties	Can be used to specify properties to be passed into the DriverManager.getConnection call or to be set on the Datasource instance. Note when the properties are set on the Datasource instance they need to match the case of the class setter e.g. if 'setURL' then use 'URL' as the property name.
TEST CONNECTION	Provides the option to test if a connection can be created to the database with the details currently provided.

The below screenshot shows an example of a filled JDBC proxy settings screen using a DriverManager:

Similarly the screenshot below shows an example of a filled JDBC proxy settings screen using a Datasource:

Operation modes

Ekko Proxy has four different operation modes:

• Passthrough - in this mode all requests and responses going through the proxy will be passed directly to the target server or database.
• Record - this mode will save all requests and responses going through the proxy to the target server or database.
• Playback - in the playback mode HTTP proxies will respond with a recorded or mocked response, if one exists, otherwise it will pass the request to the target server and respond with the server's response.
  For JDBC proxies the playback option works using a mocked connection so no database calls will reach the target database in this mode. If there are any recorded or mocked responses that match a request then these will be played back and if not you would get an empty result set, say for a executeQuery call. So to get proper responses you can either run in Passthrough or Record mode first to capture responses or setup mocks in the Mock Editor.
• Playback or Record - in the playback or record mode Ekko Proxy will respond with a recorded/mocked response, if one exists, otherwise it will pass the request to the target server and record the response so that when the same request is seen again it will be played back from thereon.
  Note this mode is not supported for JDBC proxies.
• Playback on Error - this mode will only playback a saved or mocked response (provided either exists) if a HTTP error status of 500 or above is received from the target server. If a recording or mock does not exist the original error response is sent.
  Note this mode is not supported for JDBC proxies.

The different operation modes for HTTP proxies are explained further in the below flow diagram:

Organising recordings

The 'Organising Recordings' table along with the 'Use request URI in output path' field allows you to organise how the recordings are stored on disk under the 'Output Directory' path.

For example if you have set 'Output Directory' to C:\temp, selected the 'Use request URI in output path' option and you have the following SOAP request on the /SystemUtilitiesService URI:

<?xml version="1.0" encoding="UTF-8"?>
   <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" ...>
   <soapenv:Body>
      <GetSystemFunctionsRequest xmlns="urn:EkkoProxy.SystemUtilities.V1">
         <Header>
            <ns1:Origin xmlns:ns1="urn:EkkoProxy.Schema.Header">app</ns1:Origin>
            <ns2:UserId xmlns:ns2="urn:EkkoProxy.Schema.Header">789012</ns2:UserId>
         </Header>
         <SystemFunctions>
            <ApplicationId>2</ApplicationId>
            <ApplicationType>3</ApplicationType>
            <SystemParameters>
               <SystemParameter>
                  <ParameterIdentifier>IsAvailable</ParameterIdentifier>
               </SystemParameter>
            </SystemParameters>
         </SystemFunctions>
      </GetSystemFunctionsRequest>
   </soapenv:Body>
</soapenv:Envelope>

And you wanted to store these and other requests of the SystemUtilitiesService under the method requested and the user id, as highlighted above, you could add the following XPaths to the 'Organising Recordings' table:

1. local-name(//Envelope/Body/*[1])
2. //UserId/text()

The order of the expressions determine the sub-folder order, which given all of the above would end up being:

C:
|_ temp
   |_ SystemUtilitiesService
      |_ GetSystemFunctionsRequest
         |_ 789012
               - 2c94b878a468ce4b3a9a2a3ea37df739_req.txt
               - 2c94b878a468ce4b3a9a2a3ea37df739_resp.txt

The *_req.txt and *_resp.txt files contain the recorded request and response respectively.

Likewise if you are working with JSON etc. you can use JsonPath or regular expressions instead pick out values e.g. $.userId or \"userId\":\s?\"(.*)\" (note the group brackets used to select the value part only) would fetch the value of the userId field given JSON like:

{
    "userId":"JohnDoe"
    .
    .
}

Note you can change the response content of a saved response file at any time to have the amended response played back on the next request for the resource.

The recorded requests can also be dragged & dropped on a Ekko Proxy (messages table part) to resend them provided the proxy is running in passthrough mode.

Likewise recordings can be organised for JDBC proxies. By default they are organised by the given mock path and the JDBC command's object and method. For example calling executeQuery on a PreparedStatement would create a folder structure as: C:\temp\sqlrequest\PreparedStatement\executeQuery provided the output directory was 'C:\temp' and the mock path was '/sqlrequest'.

To organise further you can specify one or more regular expressions. For example to organise by the database table name used in a query you could simply use: FROM ([a-zA-Z_]*) to extract the table name from the SQL query. This will then be appended to the output path e.g. C:\temp\sqlrequest\PreparedStatement\executeQuery\SomeTableName.

Normalise recordings

The 'Normalise Recordings' table allows for normalising recordings by removing any unwanted uniqueness thus enabling them to be played back.

For example given a SOAP request message like:

<?xml version="1.0" encoding="UTF-8"?>
   <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" ...>
   <soapenv:Body>
      <GetSystemFunctionsRequest xmlns="urn:EkkoProxy.SystemUtilities.V1">
         <Header>
            <ns1:Origin xmlns:ns1="urn:EkkoProxy.Schema.Header">app</ns1:Origin>
            <ns2:UserId xmlns:ns2="urn:EkkoProxy.Schema.Header">789012</ns2:UserId>
            <ns3:TransactionId xmlns:ns3="urn:EkkoProxy.Schema.Header">3M4bSjb3jP4b2j3hL</ns3:TransactionId>
         </Header>
         <SystemFunctions>
            <ApplicationId>2</ApplicationId>
            .
            .
         </SystemFunctions>
      </GetSystemFunctionsRequest>
   </soapenv:Body>
</soapenv:Envelope>

In the example above the TransactionId is a unique identifier that differs per request, which if not excluded, would create a new recording every time and you would not be able to have it played back. So to overcome this scenario you can add expressions in the 'Normalise Recordings' table to exclude this, and any other data items like it, from the unique key used to identify a recording.

In this particular example adding //Header/TransactionId to the 'Normalise Recordings' table would be all that's needed to exclude the node from the recording key.

Note for XPath expressions you don't have to worry about namespaces.

Similarly JsonPath and regular expressions can be used to exclude unique information in the request body as well as the request URI, although the latter cannot be done using XPath or JsonPath expressions.

For example given a REST GET request below:

http://localhost:3094/microservice/v1/books?bookId=112233&timestamp=123456789

You can exclude the unique timestamp query string parameter by adding a simple regular expression &timestamp=\d* to the 'Normalise Recordings' table.

Likewise if you need to exclude one or more unique fields in for example a JSON request body like below:

{
    "glossary": {
        "title": "example glossary",
        "GlossDiv": {
            "title": "S",
            "GlossList": [
                {
                    "ID": "ISO 8879:1986",
                    "CreatedDate": "2018-10-05T14:48:10.000Z",
                },
                {
                    "ID": "ISO 1345:1988",
                    "CreatedDate": "2018-11-15T16:32:14.000Z",
                },
                .
                .
            ]
        }
    }
}

Using either a regular expression like \"CreatedDate\"\s?:\s?\".*\", or a JsonPath like $.glossary.GlossDiv.GlossList[*].CreatedDate would exclude the CreatedDate from being part of the recording key so that if the same message is sent again but with a different CreatedDate value it will still be played back.

Note as long as the value(s) that you don't want to include in the filename key are removed then it doesn't matter if the remaining message is valid JSON or XML as it's only used for the filename key generation.

Similarly you can use regular expressions for JDBC proxies to normalise the SQL query for recording purposes. For example if you had the query below:

SELECT
  GROUP_CODE,
  GROUP_CODE_DESCRIPTION,
  LOOKUP_ID,
  LOOKUP_TYPE,
  LOOKUP_VALUE,
FROM
  LOOKUPS
WHERE
  CHANNEL LIKE ?
  AND (
     GROUP_CODE = 'GRP_ID_FOO' OR
     GROUP_CODE = 'GRP_ID_BAR'
  )

And you would like to have the same response recording played back for any GROUP_CODE values then you could add a regular expresion like: GROUP_CODE = '[A-Z_]*' to remove the group code values from the resulting filename key.

Managing a Ekko Proxy instance

Once a Ekko Proxy instance has been created, a link to it will appear in the navigation bar from where it can be managed. Clicking that link will show the Ekko Proxy management screen as can be seen in the HTTP example below:

HTTP messages going through the proxy will appear in the table as shown above.

Note the number of current messages displayed is limited without a license.

JDBC instances are very similar as shown in the example below:

Fields and functions

The fields and functions of this part of the Proxy management view are as follows:

Field	Description
HTTP/JDBC Proxy <port> <proxy description>	The proxy type followed by the port is displayed top left with the proxy description immediately below.
Search	The search field can be used to search the table showing the messages going through the Ekko Proxy instance. The search supports regular expressions. Pressing the Enter key or clicking the search button will initiate the search and filter the table showing only matches. The table header will show if it's filtered or not by displaying the filtered icon:
Link status	A green link means the Ekko Proxy client is connected to the Ekko Proxy Server. A red link means the Ekko Proxy client has been disconnected from the Ekko Proxy Server.
Proxy Information	On hover, displays proxy settings information. For HTTP proxies the following is displayed: 'Output Directory', 'Listener Https', 'Target Https', 'Output Format', 'Expression Format' and 'Certificate File' if one was configured. For JDBC proxies the information includes: 'Output Directory', 'Secure Sockets', 'Mock Path', 'User' and either the configured 'Driver' or 'DataSource'.
Target Host	The host / ip of the target server where the requests will forwarded to in passthrough or record mode. This can be edited only when the proxy is stopped. Note setting is only applicable for HTTP proxies.
Target Port	The port number [1 - 65535] of the target server where the requests will forwarded to in passthrough or record mode. This can be edited only when the proxy is stopped. Note setting is only applicable for HTTP proxies.
Verbosity Level	The verbosity level determines which JDBC commands triggers events to be fired and subsequently shown in Ekko Proxy: All: show all commands. Connections and Statements: shows commands for all connections and statements. Connections: show commands for connections only. Statements: show statement commands only. PreparedStatements: show prepared statements commands only. CallableStatements: show callable statements commands only. Note setting is only applicable for JDBC proxies.
Operation Mode	The operation mode of the Ekko Proxy instance. See the Operation modes section for a description of what the different modes of operation are. This can be edited only when the proxy is stopped.
Pause / Resume	Pressing the 'Pause' button will stop new messages from being displayed in the table whilst paused. Pressing 'Resume' will refresh the table and it will again update automatically when new messages appear. Note 'Pause' and 'Resume' only affects the view of the current client i.e. other clients viewing messages for the proxy will continue to see updates.
Stop / Play	Pressing the 'Stop' button will stop the running proxy and any requests sent to it will not be able to connect. Pressing 'Play' starts the proxy again. Whilst stopped the 'Target Host', 'Target Port' and 'Operation Mode' fields can be modified allowing a change of target destination or operation mode.
Recordings Drawer	The 'Recordings Drawer' button opens the Recordings drawer showing any existing recordings found in the output directory of the proxy.
Delay	The 'Delay' button opens the Delay Settings dialog allowing for response delays to be set.
Show Statistics	Opens the statistics dialog showing request hits and HTTP method distribution.
Compare	The 'Compare' button provides the option to compare two requests or responses in the Compare dialog. Note this button is only enabled when exactly two messages are selected.
Open	The 'Open' button opens a recorded request and/or response in a new browser tab / window. The request and/or response needs to have been recorded i.e. saved before it can be opened in a separate window. Note depending on browser settings, especially if opening both the request and response in one go, then you may need to enable pop-ups for the Ekko Proxy client as otherwise the action may be blocked by the browser.
Mock	Generates a mock from the selected request / response. You can amend etc. the generated mock in the Mock Editor as required after it's been generated. Note you must stop & start the proxy(s) that you want to pick up the new generated mock.
Save	The 'Save' button allows for saving / recording the requests and responses of the selected messages that are not already saved / recorded or played back i.e. messages that were passthrough messages.
Resend	Resends the selected requests.
Clear	Clears the selected messages from the table and in-memory Ekko Proxy server cache.
Delete	Deletes the selected saved / recorded messages from disk. Note this cannot be undone!

Messages table

The messages table displays the incoming requests/responses going through the proxy. Saved request recording files can also be dragged & dropped on this table to send these requests again (Note to reach the target server, the Ekko Proxy should not be in Playback mode).

The following describes the messages table columns:

Field	Description
Time	The timestamp of the message (HH:mm:ss.SSS dd-MM-yyyy).
Method	The HTTP method of the message e.g. POST. Note this is only applicable for HTTP proxies.
Status	For HTTP proxies this is the HTTP status of the message e.g. 200 OK. For JDBC proxies it will say 'Success' if there were no SQL error or 'Failed' followed by an error code if an SQL error occurred.
Mode	The operation mode used to serve the message e.g. Playback.
Request Url	For HTTP proxies this is the request URL of the HTTP message. For JDBC proxies this is the 'request URL' or rather command path of the SQL request. It is comprised of the JDBC object name followed by the method called on it e.g. /PreparedStatement/executeQuery. For more information see JDBC mocking.
Filename	The filename of the recording if the message was recorded or played back.
Duration	The length of time it took to respond (mm:ss.SSS). If a delay is set for the request then this time will include the delay time and a timer icon is displayed to indicate that it was a delayed response.

Note multiple messages can be selected by clicking the check box or by holding down the Ctrl key while clicking on a message row.

For HTTP proxies request recordings can be dragged & dropped on to the messages table to send them again as shown in the example below:

Recordings drawer

The Recordings drawer displays a list of any recordings found in the output directory of the proxy:

The Recordings drawer lists the request line and filename for each recording. If multiple recordings exist for a particular request then these are grouped together. Clicking on an recording will display the details of the request and response (provided one exists) in the Request Details section. Recordings can be filtered by entering a regular expression enabled search string. Lastly recordings can be either imported or exported by clicking the Import/Export button .

A context menu can be accessed by clicking the more button () providing the following menu options:

Menu Item	Description
Delete Recording	Deletes the selected saved / recorded messages from disk. Note this cannot be undone!
Open Request	Opens the request file in a new browser tab / window.
Open Response	Opens the response file in a new browser tab / window.
Send Request	Resends the selected request.

Note a license is required for showing all recordings in the drawer.

Request and response details

The second half of the Proxy management view shows the request and response details of a selected message as shown below.

The request details are editable allowing for a new request to be created or for amending an existing one. When creating a new request the details can either be entered manually, selected from the Recordings drawer or a saved request recording can be dragged & dropped in the Request Details area - the latter applies only to HTTP proxies.

Request Details

The top part of the HTTP request details section is shown below:

The fields and functions of this part of the Proxy management view are:

Field	Description
Request Method	The request HTTP method of the currently selected request, if any. The field is editable allowing for it to be set or changed.
Request Url	The request URI of the currently selected request, if any. The field is editable allowing for it to be set or changed.
Send	The 'Send' button will send / resend the current request content.
Response Status	The HTTP response status for a request is shown directly below the Send button in the tab area.

For JDBC proxies this looks like:

The SQL details shows the JDBC 'Request URL' i.e. command path consisting of the object name and method. To the right there is a resend button that's enabled for requests that can be re-executed.

Request tab

For a HTTP proxy the request tab displays the message body of the HTTP request:

By default the data is displayed according to the output format setting. A speed dial menu at the bottom right of the area provides the following display options:

Field	Description
Strip before send	When on, the message (XML or JSON only) will have any formatting stripped off before the request is sent. Conversely when off, the message is sent as is displayed.
Formatting	Turns the formatting and syntax highlighting on/off. If you edit the request, with a view to send an altered message, then the version you are editing (formatted or raw) is the only one altered and the message is sent as displayed. The option is not available if the output format is set to None.
Word wrap	Turns line word wrapping on/off.

Similarly for a JDBC proxy the request tab displays the SQL, if applicable, of the request:

Response tab

For a HTTP proxy the response tab displays the message body of the HTTP response.

By default the data is displayed according to the output format setting. A speed dial menu at the bottom right of the area provides the following display options:

Field	Description
Formatting	Turns the formatting and syntax highlighting on/off. The option is not available if the output format is set to None.
Word wrap	Turns line word wrapping on/off.

For a JDBC proxy the response tab displays the SQL response.

If the response is a result-set then it will be displayed in a tabular format. The table is searchable and the data can be downloaded as a CSV file. A speed dial menu at the bottom right of the area provides the following display options:

Field	Description
Table view	Swaps between displaying the data in tabular or json format.
Word wrap	Turns line word wrapping on/off. This is only available if the response is not in tabular format.

Headers tab (HTTP)

The headers tab displays the HTTP message request and response headers.

The request headers can be edited in either table or bulk () modes. In bulk view mode headers are displayed all together as shown below:

Cookies tab (HTTP)

The cookies tab shows the request cookie and the response set-cookie HTTP headers in table form making them easier to view and edit (former only).

The code button () toggles between displaying values Url encoded or decoded.

For details of the standard cookie properties listed in the response cookies table see Cookie Specification.

Note HTTP request recordings can be dragged & dropped on the Request Details area to fill it with the request details of the recording as seen below:

Parameters tab (JDBC)

The parameters tab displays the query parameters for the SQL command, if applicable.

The parameters can be edited and the SQL command sent again with the new parameter values.

Client Info tab (JDBC)

The client info tab displays information that can be set by a client when connecting.

By default the client's IP address (ep-jdbc-client.address) and host name (ep-jdbc-client.name) are always sent. More client information properties can be set via system properties by passing the system property names to lookup via a semicolon delimited string set in a property named ekkoproxy.jdbc.clientinfo.properties when connecting.

Creating a virtual API manually

Creating virtual services manually (as opposed to record & playback) can be achieved in a couple of ways as explained further in the following sections.

Using recordings

Creating a virtual HTTP response message can be done by firing the request in question through the proxy and then performing the save action to record the request. This generates the request recording file e.g. 34af1895bca9eef210ae5836e0ae65be_req.txt in the Output Directory as per organising recording rules. You can then simply create an equivalent response file e.g. 34af1895bca9eef210ae5836e0ae65be_resp.txt and put the desired response status and content in that file. The format of the response file should follow the HTTP Specification which very simply put is:

Status line
Response headers (if any)
CRLF
Response body (if any)

Example:

HTTP/1.1 200 OK
Content-Type: text/xml
Server: gSOAP/2.9

<?xml version="1.0" encoding="UTF-8"?>
   <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" ...>
   <soapenv:Body>
      <GetSystemFunctionsRequest xmlns="urn:EkkoProxy.SystemUtilities.V1">
            .
            .
      </GetSystemFunctionsRequest>
   </soapenv:Body>
</soapenv:Envelope>

Using WireMock

Ekko Proxy comes with a Mock Editor tool (see below) which manages WireMock mocks that can be created and then used by the proxy instances to serve mocked responses - no coding required. Dynamic responses can be created though, using Handlebars templating, giving you great flexibility.

For more details please see Ekko Proxy WireMock Editor

Note the WireMock configuration files created by the Mock Editor can also be copied and used in traditional WireMock based integration test suites, though not all functionality will be available.

Connecting to a proxy

Connecting to an EkkoProxy proxy instance is pretty easy as described in the following sections.

HTTP proxy

Once a EkkoProxy HTTP proxy instance is running on a port then you can configure your application to go through the proxy by repointing the application service endpoints to the hostname and port of where Ekko Proxy instance resides. For example if Ekko Proxy is running on localhost and you created a HTTP proxy on port 3080 then you would use http://localhost:3080.

Forwarding

There can be situations where the port, that an Ekko Proxy is created on, cannot be exposed outside of that machine be it due to firewalls or cloud restrictions etc. In those cases requests can be 'forwarded' to the Ekko proxy/proxies using a special /forward/<port> path as in the example endpoints below:

http://localhost:4040/forward/3080/MyService
or
http://ekkoproxy.mybluemix.net/forward/3080/MyService

Note using this feature will consume threads from the main Tomcat thread pool rather than the individual Ekko Proxy thread pools.

JDBC proxy

How you connect to a EkkoProxy JDBC proxy will depend on your client application's configuration. The legacy approach to loading JDBC drivers (before JDBC version 4 and Java SE 1.6) was to load it manually like below:

Class.forName("com.lcasoft.ekkoproxy.db.jdbc.EkkoProxyDriver");

This should not be necessary however as the ekkoproxyjdbc-1.5.jar will register the driver as a service and you only need to add the jar to your application's classpath.

Once added you can get JDBC database connections by configuring your application with a JDBC URL connection string for the EkkoProxy JDBC proxy instance instead of your actual database. You can connect to the EkkoProxy JDBC proxy instance using HTTP or RMI.

The EkkoProxy JDBC connection string has to start with jdbc:ekkoproxy: which identifies the EkkoProxy JDBC driver. This is then followed by the proxy connection URL starting with the protocol; http, https or rmi. Note that https can only be used if the EkkoProxy application itself has been setup to run on https. After the protocol you must specify the server hostname where EkkoProxy is running followed by a port number. If using http(s) it will be the port number of the EkkoProxy application itself otherwise for rmi its the port of the EkkoProxy JDBC proxy instance. This is then followed by the EkkoProxyJdbc identifier. For rmi connections that is all that is needed and for http(s) you will need to specify the port number of the EkkoProxy JDBC proxy instance last. This is probably best explained with a few example connection URLs as shown below:

DriverManager.getConnection("jdbc:ekkoproxy:http://localhost:4040/EkkoProxyJdbc/2001");
or using RMI:
DriverManager.getConnection("jdbc:ekkoproxy:rmi://localhost:2001/EkkoProxyJdbc");

Dialogs

Expressions test dialog

The Expressions test dialog allows you to verify what your Regex, XPath or JSonPath expressions match and produce the expected results.

In the example below two Normalisation key exclude XPath expressions are to be tested against a SOAP message:

The expressions to be tested in the example are:

• /Envelope/Header/RequestHeader/networkCode
• /Envelope/Header/RequestHeader/applicationName

Clicking 'Test It' will result in the below test result:

This shows the difference with fields removed highlighted in red meaning these fields will not be considered as part of the recorded normalised filename key. In the example above the same result could have been achieved with shorter expressions e.g. //RequestHeader/networkCode or even in one expression e.g. /Envelope/Header or //Header/RequestHeader removing the whole SOAP header instead - that is provided you didn't want to include any of the headers.

It's usually better to be specific unless you know you want to remove all SOAP headers for example for all the messages going though the proxy.

Note not all expressions have to match all messages - if an expression doesn't match it's simply ignored.

Another example would be when testing 'Organising Recordings' reqular expressions as in the example below:

The expressions to be tested in this example are:

1. Channel:\s?(.*)
2. \"name\"\s?:\s?\"(.*)\"

Clicking 'Test It' will result in the below test result:

The result shows the matches as part of the file path that they will be part of. If the 'Output Directory' is set to say C:\temp then the final recording path would be C:\temp\myChannel\my_username or C:\temp\user\myChannel\my_username if 'Use Request URI in Output Path' was selected and the URI for the service is /user.

Delay settings dialog

The delay settings dialog allows for response delays to be set for requests who's responses are being played back.
The dialog will show requests currently displayed in the messages table or that has been previously set for the proxy.

To set a delay choose the Request URI and Method, either from the dropdowns or the table, that you want to set/change and use the slider to set a minimum and maximum delay for the particular response.

The max delay slider on the right changes the max delay possible (up to 2 minutes). This also sets the scale of the delay slider itself allowing for either finer or more coarse-grained timings to be set.

Note a license is required for full delay functionality.

Compare dialog

The compare dialog can show the differences between two selected requests or responses. The example below shows the differences between two responses.

The compare dialog provides either a Split View or Unified View of the differences.

Finally there is an option to compare with or without word-wrapping.

Tools

The tools section of Ekko Proxy brings various useful everyday tools to you securely! You can find many of these tools online but how secure are they? Do you feel comfortable using them and does When working with sensitive data e.g. customer data etc. then it's not secure to use online tools to work with this data.

The following sections describe the Ekko Proxy tools that you can use knowing that your data is safe.

Note you can press Ctrl+Enter / Cmd+Enter within the input field to execute the selected action.

You can press F1 to get details of all the text editor shortcuts. Below is a list of the basic editor shortcuts.

Compare

The Compare tool allows you to compare two pieces of textual content and view the difference in Split or Unified mode. You can also toggle word-wrap on / off and the content can be formatted in JSON, XML, HTML, Javascript/Typescript, and SQL format.

Encoding

The Encode tool provides Base64, Base64 Url, and Url encode and decode functionality.

Formatting

The Format tool allows you to perform JSON, XML and SQL formatting actions with your choice of preferred indentation level, if any.

Hashing

The Hash tool provides the ability to perform various hashing algorithms like MD5, various versions of SHA and many others.

The supported hashing algorithms are: Adler-32, CRC-32, CRC-32c, Farm Hash FingerPrint-64, MD5, Murmur3-32, Murmur3-128, SHA-1, SHA-256, SHA-384, SHA-512, and SipHash-2-4.

Note weaker hashing algorithms like MD5 and SHA-1 are no longer considered safe!

JWT

The JWT tool allows you to validate or encode JWT (signed) tokens safely on your own machine i.e. there is no need to use your secret keys on insecure online tools.

The supported JWT signing algorithms are: HMAC-SHA (HS256, HS384, HS512), RSASSA-PKCS (RS256, RS384, RS512), ECDSA (Elliptic Curve - ES256, ES384, ES512), and RSASSA-PSS (PS256, PS384, PS512).

When using HMAC-SHA you can use raw or base64 encoded secret keys selecting the 'Base64 Encoded' checkbox if using the latter.

Keys for signing or validating the JWT tokens can either be provided or generated (licenced version only) using the Generate Secret/Keys button.

Note a license is required for full JWT functionality.

Matching

The Match tool gives you the ability to test Regex JS, Regex Java, XPath or JsonPath expressions.

The flags for Regex JS and Java are:

• Global (g): matches the pattern multiple times.
• Ignore case (i): makes the regex case insensitive.
• Multiline (m): enables multi-line mode. Where ^ and $ match the start and end of the entire string. Without this, multi-line strings match the beginning and end of each line.
• dotAll (s): short for single line, it causes the . to also match new line characters.
• Unicode (u): enables support for unicode.

The flags for XPath are:

• Namespace aware (n): sets whether the parsing of the XML should be aware of namespaces or not. If namespaces aware then the XPath expression must also use namespaces for matching elements that have a namespace.

The Match Details section shows the more details on the regular expression matches and any group matches e.g.:

WSDL

The WSDL tool allows you to open and view a WSDL definition file and generate mocks from it. The WSDL definition is visualised in a tree structure as can be seen below.

A WSDL definition file can be loaded from either a local file (e.g. C:\EkkoProxy\SomeSoapServices.wsdl), a url (e.g. https://www.dataaccess.com/webservicesserver/numberconversion.wso?WSDL) or it can be uploaded via the upload button . The upload button will open the dialog below.

You can either click to select a folder or ZIP file containing the WSDL definition file and any potential XSDs or simply drag & drop the files.

Once the WSDL definition is loaded it is possible to generate one or more mocks by clicking the 'Generate Mock...' button. This opens the Generate Mocks dialog as shown below where operations can be selected for which mocks will be generated.

Once generated the mock(s) can be found in the Mock Editor where the mock(s) can be modified if / as required.

Note you will need to stop / start any running proxies that you want to pick up the newly generated mock(s).

The SOAP responses are generated based on the 'Message flags' which are all enabled by default. The options are:

• Build headers (h): the generated SOAP message will contain a SOAP header.
• Build optional (o): optional elements will be generated in the SOAP message.
• Example content (e): example content based on the data type will be generated. If disabled a question mark will be generated instead.
• Type comments (t): a comment will be generated before each element describing it's data type.
• Value comments (v): for enum type values a comment with all the possible values will be generated before the element.

Before generating mock(s) you can view what the generated SOAP message will look like, based on the message flags above, by clicking the generate request / response icon next to an operation. Request and response nodes will then appear under the operation which shows the generated SOAP message when selected.

OpenAPI

The OpenAPI tool allows you to open and view a OpenAPI definition file and generate mocks from it. The OpenAPI definition is visualised in a tree structure as can be seen below.

A OpenAPI definition file (JSON or YAML) can be loaded from either a local file (e.g. C:\EkkoProxy\openapi.yaml), a url (e.g. https://petstore3.swagger.io/api/v3/openapi.json) or it can be uploaded via the upload button . The upload button will open the dialog below.

You can either click to select an OpenAPI YAML or JSON definition file or simply drag & drop one in.

Once the OpenAPI definition is loaded it is possible to generate one or more mocks by clicking the 'Generate Mock...' button. This opens the Generate Mocks dialog as shown below where responses can be selected for which mocks will be generated. If a response supports more than one media type then you can select which one to use.

Once generated the mock(s) can be found in the Mock Editor where the mock(s) can be modified if / as required.

Note you will need to stop / start any running proxies that you want to pick up the newly generated mock(s). Also note that if generating more than one mock response for the same API then they will have a 'mockstatus' query string added by default (equal to the response code) which is to distinguish between the requests and their corresponding responses. This can be amended in the Mock Editor afterwards if a different request matching mechanism is required.