From version < 11.8 >
edited by Jerome Brongniart
on 2019/03/11 13:43
To version < 12.1 >
edited by Dorian Cransac
on 2019/03/26 11:18
< >
Change comment: There is no comment for this version

Summary

Details

Page properties
Title
... ... @@ -1,1 +1,1 @@
1 -Services & Remote APIs
1 +STEP Client
Author
... ... @@ -1,1 +1,1 @@
1 -xwiki:XWiki.jeromebrongniart
1 +xwiki:XWiki.doriancransac
Content
... ... @@ -1,11 +1,11 @@
1 1  (% class="box warningmessage" %)
2 2  (((
3 -The Java APIs and libraries discusses in this section are currently only available in STEP Enterprise Edition
3 +The Java APIs and libraries (STEP Client) discussed in this section are currently only available in STEP Enterprise Edition
4 4  )))
5 5  
6 -= High-level functionality =
6 += Introduction =
7 7  
8 -High-level functionality and means to connect to the controller programmatically are exposed in the class ControllerClient. The Javadoc of the remote client API is available at: [[https:~~/~~/www.exense.ch/static/javadoc-remote-client/>>url:https://www.exense.ch/static/javadoc-remote-client/]] and examples are available in [[https:~~/~~/github.com/exense/step-enterprise-samples>>url:https://github.com/exense/step-enterprise-samples]].
8 +The STEP client exposes means to connect to the controller programmatically, access and use STEP services in a headless way via the class STEPClient. The Javadocs of each individual remote client is available at: [[https:~~/~~/www.exense.ch/static/javadoc-remote-client/>>url:https://www.exense.ch/static/javadoc-remote-client/]] and examples are available in [[https:~~/~~/github.com/exense/step-enterprise-samples>>url:https://github.com/exense/step-enterprise-samples]].
9 9  
10 10  As a "headless" user (i.e assuming you're wanting to automate interactions with STEP, which are part your build pipeline, for instance) you will probably want to perform the following tasks programmatically:
11 11  
... ... @@ -14,73 +14,85 @@
14 14  * download existing plans
15 15  * access execution metadata and execution results (report nodes)
16 16  
17 -That's what the class ControllerClient is intended for.
17 +All of these workflows are supported by STEP's java client. REST interactions also work and you can decide to build your automated workflows that way, but they are not the preferred way to do this, as REST signatures are subject to changes and they are not documented. Therefore, only limited support will be provided.
18 18  
19 -= Main Controller Services =
19 += Plugin Services =
20 20  
21 -In addition to the class ControllerClient, other classes are made available. Each class interacts with a certain type of entity in STEP and allows either:
21 +When interactive with STEP in a headless way, we believe it is best to learn by example, which is why we've provided examples (see link at the beginning of the section) and put emphasis on the javadocs. However, certain services, such as the Event Broker, require deeper explanations. This is due to the fact that understanding certain subtleties in the implementation can make a big difference in how you'll want to use the service.
22 22  
23 -- basic CRUD operations on these entities
23 +== EventBroker ==
24 24  
25 -- the execution of these entities (for those which can be executed)
25 +The EventBroker Service and API allow asynchronous communication to happen in step as well as synchronization between keywords, between plans and between keywords and plans. It is particularly useful in scenarios where a thread (or a "user") needs to wait for specific events before performing the next task.
26 26  
27 -- querying, browsing or printing these entities
27 +These events can be created internally (from within a keyword or plan) using various types of clients (Java, REST, prepop Keywords and Artefacts). The service also exposes methods for testing the presence of an event, reading it's content, consuming it, etc.
28 28  
29 -The class ControllerClient relies on them to perform the higher level tasks listed in the section "High-level functionality". Javadoc links will be added in this section in the near future.
29 +== Id's vs Groups ==
30 30  
31 -== Plan Repository ==
31 +Events can be declared and targeted either through a unique identifier or a group & name combination. This is an important choice as it will impact the way you'll be using the API and how Events are managed. Here's the underlying reason behind each of these approaches:
32 32  
33 -This service can be used to access and save plans remotely.
33 +=== Id-based declaration ===
34 34  
35 -== Artefact Repository ==
35 +Setting a unique identifier in the Id field of the Event object, as you could assume, will allow for the explicit manipulation of that event instance and only that event instance. This could be seen as the standard scenario in which the consumer of the event knows exactly what event they are waiting for and how to identify it.
36 36  
37 -This service can be used to access and save artefacts remotely.
37 +It is important to note that the consumer has to be aware of the **exact **identifier **ahead of time**, or it will not be able to retrieve the event. Since the identifier is unique and is set dynamically, this is a strong constraint.
38 38  
39 -== Remote Runner ==
39 +=== Group & Name declaration ===
40 40  
41 -This service can be used to run plans remotely.
41 +Groups are designed to gather and store distinct, yet similar events. You can see this as a relaxed constraint on the identifier as consumers will be able to consumer any event from the group and no guarantee will be provided as to which Event instance specifically will be resolved. In other words, groups allow for the management of **pools of events** which share a common purpose.
42 42  
43 -== ReportTreePrinter ==
43 +Consumers only need to be aware of the Group identifier, which is a **static string**. In addition to the Group field, providers have the option to also set a name for the Event. The name field provides consumers with the ability to uniquely identify an event after it's been retrieved based it's Group.
44 44  
45 -This service can be used to access and print reports originating from a certain execution plans remotely.
45 +(% class="box infomessage" %)
46 +(((
47 +In a Group & Name scenario, names can also be used indirectly as a unique identifier within the group, allowing for the logical grouping of events while maintaining a strong constraint on Event query resolution. This comes however at the cost of performance. Users themselves have to be aware of the trade-off between performance and ease of management and need to run their own tests to find out what fits their needs best.
48 +)))
46 46  
47 -= Plugin Services =
50 +== Using the Java API ==
48 48  
49 -== EventBroker ==
52 +The STEPClient class provides access to a RemoteEventBrokerClient class, which exposes most of the broker's primitives.
50 50  
51 -The EvenBroker Service and API allow asynchronous communication and synchronization between keywords, between plans and between keywords and plans. It is particularly useful in scenarios where a user needs to wait for specific events before performing the next task. These events can be created internally (from a keyword or plan) using various types of clients (REST, Java API, the PushEvent artefact, which will be published soon) or externally, by adding an additional layer in order to transform the signature of custom user notifications (i.e a business-specific event signature and endpoint) into a standard step event. The service also exposes methods for testing the present of an event, reading it's content, consuming it, etc. Finally, a standard enterprise artefact called "WaitForEvent" allows users to synchronize the execution of test plan blocks with the occurence of a user-defined type of event.
54 +=== Primitives ===
52 52  
53 -= Code examples =
56 +* **Put**:** **upload an event to the broker
57 +* **Peek**: download a copy of the event, leaving the existing event untouched in the Broker
58 +* **Consume**: download and exhaust the event
54 54  
55 -== EventBroker ==
60 +=== Example ===
56 56  
62 +Initializing the client:
63 +
57 57  (% class="box infomessage" %)
58 58  (((
59 -~/~/ Event manipulation based on a unique id
66 +RemoteEventBrokerClient client = new StepClient("http:~/~/my-step-controller:8080", "admin", "init").getEventBrokerClient();
67 +)))
60 60  
61 -Event sentEvent = new Event().setId("a_unique_id");
69 +Creating, uploading, and consuming an event by **Id**:
62 62  
63 -client.putEvent(sentEvent);client.peekEvent("a_unique_id");
64 -
71 +(% class="box infomessage" %)
72 +(((
73 +Event sentEvent = new Event().setId("a_unique_id");client.putEvent(sentEvent);
74 +client.peekEvent("a_unique_id");
65 65  Event readEvent = client.consumeEvent("a_unique_id");
66 -
67 67  System.out.println(readEvent);
77 +)))
68 68  
79 +Creating, uploading, and consuming an event by **Group & Name**:
69 69  
70 -~/~/ Event manipulation based on a "family" of events (no unique id known, it will be generated by step)
71 -
72 -Event sentEvent = new Event().setGroup("myGroup").setName("myEventName");
73 -
74 -client.putEvent(sentEvent);
75 -
81 +(% class="box infomessage" %)
82 +(((
83 +Event sentEvent = new Event().setGroup("myGroup").setName("myEventName");client.putEvent(sentEvent);
76 76  client.peekEventByGroupAndName("myGroup", "myEventName");
77 -
78 78  Event readEvent = client.consumeEventByGroupAndName("myGroup", "myEventName");
79 -
80 80  System.out.println(readEvent);
81 81  )))
82 82  
89 +== Artefacts and Keywords ==
83 83  
91 +Various artefacts and keywords have been pre-populated in step for convenience.
92 +
93 +=== WaitForEvent artefact ===
94 +
95 +
84 84  Assuming some event of group "##myGroup"## and of name "##myEventName"##is sent by a third party EventBrokerClient, the following plan will wait for the event to be received and then store the content of the event in the variable "result":
85 85  
86 86  [[image:Screen Shot 2018-07-11 at 16.58.11.png||style="float:left"]]
... ... @@ -97,6 +97,16 @@
97 97  
98 98  [[image:Screen Shot 2018-07-11 at 16.58.32.png||height="136" width="252"]]
99 99  
112 +The same applies with the Id-based approach, i.e you need to leave the Group & Name fileds empty and only set the Id.
113 +
114 +(% class="wikigeneratedid" %)
115 += EventBrokerMonitor =
116 +
117 +
118 +(% class="wikigeneratedid" %)
119 += 24/7 persistent monitoring =
120 +
121 +
100 100  = Plan examples =
101 101  
102 102  (% class="box infomessage" %)
Copyright © exense GmbH
v1.0