documentation of the available interface.

multiple script upload is supported in multi threading.
preparing release 2.1.4

Author: danieldanan

README.md

@@ -25,14 +25,14 @@ The library is published to Maven Central under the coordinates `com.microfocus.
 <dependency>
     <groupId>com.microfocus.adm.performancecenter</groupId>
     <artifactId>plugins-common</artifactId>
-    <version>1.2.3</version>
+    <version>1.2.4</version>
 </dependency>
 ```
 
 ### Gradle dependency
 
 ```groovy
-implementation 'com.microfocus.adm.performancecenter:plugins-common:1.2.3'
+implementation 'com.microfocus.adm.performancecenter:plugins-common:1.2.4'
 ```
 
 ## Main client interface
@@ -79,6 +79,165 @@ The main API contract is `PcRestProxyClient` in:
   - `extractTestIdFromString(...)`, `readYaml(...)`, `GetPcServer()`, `GetTenant()`
   - Utility methods for parsing and context access.
 
+### Transport security (HTTP vs HTTPS)
+
+The transport protocol is supplied by the caller when constructing `PcRestProxy`
+(the `webProtocolName` argument, typically `"https"` or `"http"`).
+
+- **HTTPS is recommended for all real and production environments.** Credentials
+  (Basic authentication and token-based authentication) and session cookies are only
+  protected in transit when HTTPS is used.
+- **HTTP is allowed but not recommended.** It is supported on purpose so that customers
+  can evaluate OpenText Enterprise Performance Engineering (LoadRunner Enterprise) in
+  development/test environments that do not have an SSL certificate configured. Over plain
+  HTTP, credentials and cookies are transmitted unencrypted; do not use HTTP outside of
+  isolated, non-production environments.
+
+### Full interface reference
+
+Every method declared in `PcRestProxyClient` is documented below. Methods marked
+`@Deprecated` are retained for backward compatibility; prefer the lower-case named
+replacements.
+
+#### Authentication / session
+
+- `boolean authenticate(String userName, String password)`
+  - Opens an authenticated session. When the proxy is configured for token authentication,
+    `userName`/`password` are the client id key and secret key; otherwise they are the ALM
+    user name and password. Returns `true` on success.
+- `boolean logout()`
+  - Closes the authenticated session. Returns `true` on success.
+- `String GetPcServer()`
+  - Returns the resolved enterprise Performance Engineering server (host) the proxy targets.
+- `String GetTenant()`
+  - Returns the resolved tenant suffix associated with the server, or an empty string when
+    no tenant is present.
+
+#### Run lifecycle
+
+- `PcRunResponse startRun(int testId, int testInstanceId, TimeslotDuration timeslotDuration, String postRunAction, boolean vudsMode, int timeslot)`
+  - Starts a performance run for the given test and test instance, using the supplied
+    timeslot duration, post-run action, VUDs mode, and timeslot id. Returns the created run
+    (including its id and state).
+- `boolean stopRun(int runId, String stopMode)`
+  - Stops the run identified by `runId` using the given stop mode (for example a graceful or
+    immediate stop). Returns `true` on success.
+- `PcRunResponse getRunData(int runId)`
+  - Returns the current data/state for the specified run.
+
+#### Run artifacts and logs
+
+- `PcRunResults getRunResults(int runId)`
+  - Returns the collection of result artifacts available for the run.
+- `boolean GetRunResultData(int runId, int resultId, String localFilePath)`
+  - Downloads a single run result (identified by `resultId`) to `localFilePath`. Returns
+    `true` on success.
+- `PcRunEventLog getRunEventLog(int runId)`
+  - Returns the event log records produced during the run.
+
+#### Script management
+
+- `int uploadScript(String testFolderPath, boolean overwrite, boolean runtimeOnly, boolean keepCheckedOut, String scriptPath)`
+  - Uploads the script at `scriptPath` into the test plan folder `testFolderPath`. Flags
+    control overwrite behavior, runtime-only upload, and whether the script is kept checked
+    out. Returns the new script id.
+- `PcScripts getScripts()`
+  - Returns all scripts visible in the current project.
+- `PcScript getScript(int Id)`
+  - Returns the script identified by its numeric id.
+- `PcScript getScript(String testFolderPath, String scriptName)`
+  - Returns the script located by folder path and script name.
+- `boolean deleteScript(int scriptId)`
+  - Deletes the script identified by `scriptId`. Returns `true` on success.
+
+#### Test plan folders
+
+- `PcTestPlanFolders getTestPlanFolders()`
+  - Returns the test plan folder structure for the project.
+- `boolean verifyTestPlanFolderExist(String path)`
+  - Returns `true` if the test plan folder at `path` exists.
+- `PcTestPlanFolder createTestPlanFolder(String existingPath, String name)`
+  - Creates a folder named `name` under the already existing folder `existingPath` and
+    returns it.
+- `ArrayList<PcTestPlanFolder> createTestPlanFolders(String[] paths)`
+  - Creates all folders required by the supplied full `paths`, creating intermediate folders
+    as needed, and returns the created folders.
+- `ArrayList<PcTestPlanFolder> createPcTestPlanFolders(ArrayList<String[]> stringsOfExistingPathFromSubjectAndOfFolderToCreate)`
+  - Lower-level variant of `createTestPlanFolders` that accepts, for each folder, a
+    `[existingParentPath, folderNameToCreate]` pair. Returns the created folders.
+
+#### Performance test definitions
+
+- `Test createOrUpdateTestFromYamlTest(String testString)`
+  - Creates or updates a test from a full YAML test definition (name, folder, and content in
+    one document). Returns the resulting test.
+- `Test createOrUpdateTestFromYamlContent(String testName, String testFolderPath, String testOrContent)`
+  - Creates or updates the test named `testName` under `testFolderPath` from a YAML content
+    (or test) document. Returns the resulting test.
+- `Test createOrUpdateTest(String testName, String testFolderPath, String xml)`
+  - Creates or updates the test named `testName` under `testFolderPath` from an XML content
+    document. Returns the resulting test.
+- `Test createOrUpdateTest(String testName, String testFolderPath, Content content)`
+  - Creates or updates the test named `testName` under `testFolderPath` from a `Content`
+    entity. Returns the resulting test.
+- `Test getTest(int testId)`
+  - Returns the full test definition for `testId`.
+- `PcTest getTestData(int testId)`
+  - Returns metadata for the test identified by `testId`.
+- `Test updateTest(int testId, Content content)`
+  - Replaces the content of an existing test identified by `testId`. Returns the updated test.
+- `boolean deleteTest(int testId)`
+  - Deletes the test identified by `testId`. Returns `true` on success.
+
+#### Test sets, test instances and timeslots
+
+- `PcTestSets getAllTestSets()`
+  - Returns all test sets in the project.
+- `PcTestSets GetAllTestSets()` *(deprecated)*
+  - Deprecated alias for `getAllTestSets()`.
+- `PcTestInstances getTestInstancesByTestId(int testId)`
+  - Returns the test instances associated with `testId`.
+- `int createTestInstance(int testId, int testSetId)`
+  - Creates a test instance linking `testId` to the test set `testSetId`. Returns the new
+    test instance id.
+- `PcTestSetFolders getTestSetFolders()`
+  - Returns the test set folder structure for the project.
+- `PcTestSetFolder createTestSetFolder(int parentId, String name)`
+  - Creates a test set folder named `name` under the folder `parentId` and returns it.
+- `PcTestSet createTestSet(String testSetName, int testSetParentId, String testSetComment)`
+  - Creates a test set named `testSetName` under `testSetParentId` with the supplied comment
+    and returns it.
+- `PcTestSet createTestSet(String testSetName, int testSetParentId)` *(default)*
+  - Convenience overload that creates a test set with an empty comment.
+- `Timeslots GetOpenTimeslotsByTestId(int testId)`
+  - Returns the open timeslots available for `testId`.
+
+#### Trend reporting
+
+- `int addTrendReport(String name, String description)`
+  - Creates a trend report with the given name and description. Returns the new trend report
+    id.
+- `int addTrendReport(String name)` *(default)*
+  - Convenience overload that creates a trend report with an empty description.
+- `TrendReportTransactionDataRoot getTrendReportByXML(String trendReportId, int runId)`
+  - Returns the transaction-level trend report data for the given trend report and run.
+- `boolean updateTrendReport(String trendReportId, TrendReportRequest trendReportRequest)`
+  - Updates the trend report identified by `trendReportId` with the supplied request. Returns
+    `true` on success.
+- `InputStream getTrendingPDF(String trendReportId)`
+  - Returns the trend report rendered as a PDF stream. The caller is responsible for closing
+    the stream.
+- `ArrayList<PcTrendedRun> getTrendReportMetaData(String trendReportId)`
+  - Returns metadata describing the runs included in the trend report.
+
+#### Helpers
+
+- `int extractTestIdFromString(String value)`
+  - Extracts a test id encoded inside a string (for example `ID:'123'`). Returns `0` when no
+    id is found.
+- `Content readYaml(String yamlContent)`
+  - Parses a YAML content document into a `Content` entity.
+
 ## Test documentation
 
 - Unit tests guide:

pom.xml

@@ -3,7 +3,7 @@
     <modelVersion>4.0.0</modelVersion>
     <groupId>com.microfocus.adm.performancecenter</groupId>
     <artifactId>plugins-common</artifactId>
-    <version>1.2.3</version>
+    <version>1.2.4</version>
     <packaging>jar</packaging>
     <name>OpenText Enterprise Performance Engineering plugins common</name>
     <description>The plugin is a common code for plugins integrated with OpenText Enterprise Performance Engineering via public REST API.</description>
@@ -29,7 +29,7 @@
                 <role>Plugin Owner and LoadRunner Enterprise RnD</role>
             </roles>
             <organization>LoadRunner Enterprise</organization>
-            <organizationUrl>https://www.opentext.com/products/loadrunner-enterprise</organizationUrl>
+            <organizationUrl>https://www.opentext.com/products/enterprise-performance-engineering</organizationUrl>
         </developer>
     </developers>
     <scm>
@@ -54,11 +54,6 @@
             <artifactId>commons-codec</artifactId>
             <version>1.16.0</version>
         </dependency>
-        <dependency>
-            <groupId>org.apache.httpcomponents.client5</groupId>
-            <artifactId>httpclient5</artifactId>
-            <version>5.2.1</version>
-        </dependency>
         <!-- https://mvnrepository.com/artifact/commons-logging/commons-logging -->
         <dependency>
             <groupId>commons-logging</groupId>

src/main/java/com/microfocus/adm/performancecenter/plugins/common/rest/PcRestProxy.java

@@ -35,6 +35,7 @@
 import org.apache.http.client.ClientProtocolException;
 import org.apache.http.client.CookieStore;
 import org.apache.http.client.CredentialsProvider;
+import org.apache.http.client.config.CookieSpecs;
 import org.apache.http.client.config.RequestConfig;
 import org.apache.http.client.methods.*;
 import org.apache.http.client.protocol.HttpClientContext;
@@ -47,7 +48,6 @@
 import org.apache.http.impl.client.CloseableHttpClient;
 import org.apache.http.impl.client.HttpClientBuilder;
 import org.apache.http.impl.conn.PoolingHttpClientConnectionManager;
-import org.apache.http.protocol.BasicHttpContext;
 import org.apache.http.protocol.HttpContext;
 import org.apache.http.util.EntityUtils;
 import org.xml.sax.SAXException;
@@ -63,7 +63,7 @@
 import java.util.List;
 import java.util.stream.Collectors;
 
-import static org.apache.hc.core5.http.HttpStatus.*;
+import static org.apache.http.HttpStatus.*;
 
 public class PcRestProxy implements PcRestProxyClient {
 
@@ -95,7 +95,7 @@ public class PcRestProxy implements PcRestProxyClient {
     private String proxyHostName;
     private int proxyPort;
     private final CloseableHttpClient client;
-    private final HttpContext context;
+    private final CookieStore cookieStore;
     private final String tenantSuffix;
     private final boolean authenticateWithToken;
 
@@ -123,15 +123,18 @@ public PcRestProxy(
         HttpClientBuilder builder = HttpClientBuilder.create()
                 .setConnectionManager(cxMgr);
 
+        // Use the RFC 6265 cookie policy so that session-deletion cookies (e.g. the
+        // LWSSO logout cookie with "expires=Thu, 01 Jan 1970 00:00:00 GMT") are parsed
+        // without emitting "Invalid cookie header" warnings from the legacy date parser.
+        RequestConfig.Builder requestConfigBuilder = RequestConfig.custom()
+                .setCookieSpec(CookieSpecs.STANDARD);
+
         // Proxy setup
         if (proxyOutURL != null && !proxyOutURL.isEmpty()) {
             getProxyDataFromURL(proxyOutURL);
             HttpHost proxy = new HttpHost(this.proxyHostName, this.proxyPort, this.proxyScheme);
 
-            RequestConfig config = RequestConfig.custom()
-                    .setProxy(proxy)
-                    .build();
-            builder.setDefaultRequestConfig(config);
+            requestConfigBuilder.setProxy(proxy);
 
             if (proxyUser != null && !proxyUser.isEmpty()) {
                 CredentialsProvider credsProvider = new BasicCredentialsProvider();
@@ -142,11 +145,22 @@ public PcRestProxy(
                 builder.setDefaultCredentialsProvider(credsProvider);
             }
         }
+        builder.setDefaultRequestConfig(requestConfigBuilder.build());
         this.client = builder.build();
 
-        this.context = new BasicHttpContext();
-        CookieStore cookieStore = new BasicCookieStore();
-        this.context.setAttribute(HttpClientContext.COOKIE_STORE, cookieStore);
+        this.cookieStore = new BasicCookieStore();
+    }
+
+    /**
+     * Builds a fresh per-request {@link HttpContext} backed by the shared, thread-safe
+     * {@link CookieStore}. A new context is created for every request so that a single
+     * {@code PcRestProxy} instance can safely be used concurrently from multiple threads,
+     * while all threads continue to share the same authenticated session cookies.
+     */
+    private HttpContext createContext() {
+        HttpClientContext ctx = HttpClientContext.create();
+        ctx.setCookieStore(cookieStore);
+        return ctx;
     }
 
     public static Content getContentFromXmlOrYamlString(String xmlOrYamlTest) {
@@ -456,7 +470,7 @@ public boolean logout() throws PcException, ClientProtocolException, IOException
     }
 
     protected String executeRequest(HttpRequestBase request) throws PcException, IOException {
-        try (CloseableHttpResponse response = client.execute(request, context)) {
+        try (CloseableHttpResponse response = client.execute(request, createContext())) {
             if (!isOk(response)) {
                 String message;
                 try {
@@ -474,7 +488,7 @@ protected String executeRequest(HttpRequestBase request) throws PcException, IOE
     }
 
     protected CloseableHttpResponse executeRawRequest(HttpRequestBase request) throws PcException, IOException {
-        CloseableHttpResponse response = client.execute(request, context);
+        CloseableHttpResponse response = client.execute(request, createContext());
         if (!isOk(response)) {
             try {
                 String content = EntityUtils.toString(response.getEntity(), StandardCharsets.UTF_8);