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:
| |
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:
| |
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:
|
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:
|
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:

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:
- local-name(//Envelope/Body/*[1])
- //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×tamp=123456789
You can exclude the unique timestamp query string parameter by adding a simple regular expression ×tamp=\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:
|
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:
- Channel:\s?(.*)
- \"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.
Command | Shortcut Key |
---|---|
Cut line (empty selection) | Ctrl+X |
Copy line (empty selection) | Ctrl+C |
Paste | Ctrl+V |
Delete Line | Ctrl+Shift+K |
Insert Line Below | Ctrl+Enter |
Insert Line Above | Ctrl+Shift+Enter |
Move Line Down | Alt+Down |
Move Line Up | Alt+Up |
Copy Line Down | Shift+Alt+Down |
Copy Line Up | Shift+Alt+Up |
Undo | Ctrl+Z |
Redo | Ctrl+Y |
Add Selection To Next Find Match | Ctrl+D |
Move Last Selection To Next Find Match | Ctrl+K Ctrl+D |
Undo last cursor operation | Ctrl+U |
Insert cursor at end of each line selected | Shift+Alt+I |
Select all occurrences of current selection | Ctrl+Shift+L |
Select all occurrences of current word | Ctrl+F2 |
Select current line | Ctrl+L |
Insert Cursor Below | Ctrl+Alt+Down |
Insert Cursor Above | Ctrl+Alt+Up |
Jump to matching bracket | Ctrl+Shift+\ |
Indent Line | Ctrl+] |
Outdent Line | Ctrl+[ |
Go to Beginning of Line | Home |
Go to End of Line | End |
Go to End of File | Ctrl+End |
Go to Beginning of File | Ctrl+Home |
Scroll Line Down | Ctrl+Down |
Scroll Line Up | Ctrl+Up |
Scroll Page Down | Alt+PageDown |
Scroll Page Up | Alt+PageUp |
Fold (collapse) region | Ctrl+Shift+[ |
Unfold (uncollapse) region | Ctrl+Shift+] |
Fold (collapse) all subregions | Ctrl+K Ctrl+[ |
Unfold (uncollapse) all subregions | Ctrl+K Ctrl+] |
Fold (collapse) all regions | Ctrl+K Ctrl+0 |
Unfold (uncollapse) all regions | Ctrl+K Ctrl+J |
Add Line Comment | Ctrl+K Ctrl+C |
Remove Line Comment | Ctrl+K Ctrl+U |
Toggle Line Comment | Ctrl+/ |
Toggle Block Comment | Shift+Alt+A |
Find | Ctrl+F |
Replace | Ctrl+H |
Find Next | Enter |
Find Previous | Shift+Enter |
Select All Occurrences of Find Match | Alt+Enter |
Toggle Find Case Sensitive | Alt+C |
Toggle Find Regex | Alt+R |
Toggle Find Whole Word | Alt+W |
Toggle Use of Tab Key for Setting Focus | Ctrl+M |
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.