Merge pull request #182 from splunk/release/1.8.0

Release/1.8.0

Author: bparmar-splunk

.github/workflows/test.yml

@@ -14,7 +14,7 @@ jobs:
           - 1.8
         splunk-version:
           - "8.0"
-          - "8.2.0"
+          - "latest"
     runs-on: ${{ matrix.os }}
 
     services:
@@ -26,6 +26,7 @@ jobs:
           TEST_TCP_PORT: 10667
           TEST_UDP_PORT: 10668
           SPLUNK_HOME: "/opt/splunk"
+          SPLUNK_APPS_URL: https://github.com/splunk/sdk-app-collection/releases/download/v1.1.0/sdkappcollection.tgz
         ports:
           - 8000:8000
           - 8089:8089
@@ -58,7 +59,7 @@ jobs:
           echo version=${{ matrix.splunk }} >> .splunkrc
 
       - name: Test using maven
-        run: make test
+        run: mvn test -fae
         env:
           SPLUNK_HOME: "/opt/splunk"
           TEST_TCP_PORT: 10667

.idea/misc.xml

@@ -1,5 +1,31 @@
 # Splunk Enterprise SDK for Java Changelog
 
+## Version 1.8.0
+
+### New Features and APIs
+* Added a support to add custom headers in Service class. (Github PR [#176](https://github.com/splunk/splunk-sdk-java/pull/176)).
+* SSL Certificate validation (default implementation) added. (Github PR [#175](https://github.com/splunk/splunk-sdk-java/pull/175)).
+  * Boolean flag is introduced to skip/validate certificate. Use _HttpService.setValidateCertificates()_ to enable/disable certificate validation.
+  * Breaking change: Certificate validation is now enforced by default, for local or non-production use cases use _HttpService.setValidateCertificates(false)_.
+* Apps/app-install replaced with **apps/local**. (Github PR [#168](https://github.com/splunk/splunk-sdk-java/pull/168))
+* Breaking change: HttpService.useTLS flag removed, please use _HttpService.setSslSecurityProtocol()_ to set a specific SSL/TLS implementation or else TLS v1.2 is used by default for Java 1.8.
+
+### Minor Changes
+
+* External Entities restricted in XML factory. (Github PR [#180](https://github.com/splunk/splunk-sdk-java/pull/180)).
+  * Prevent expansion of external entities in Document Builder factory.
+* Headers modified in Socket creation. (Github PR [#179](https://github.com/splunk/splunk-sdk-java/pull/179)).
+  * Http Request uses raw request headers by including escape characters which seems vulnerable. It was replaced with PrintWriter methods to avoid escape characters.
+  * Host parameter used in Socket is omitted to prevent exposing it to external users.
+* README.md file modified with all login methods along with Splunk Search creation example. (Github PR [#177](https://github.com/splunk/splunk-sdk-java/pull/177)).
+* Deploy plugin is removed from Splunk module pom to avoid redundancy. (Github PR [#172](https://github.com/splunk/splunk-sdk-java/pull/172)).
+* Setter methods for Session and Bearer token added along with test case. (Github PR [#171](https://github.com/splunk/splunk-sdk-java/pull/171))
+  * **Use:** service.setSplunkToken() for session tokens and service.setBearerToken() for long-lived tokens.
+* Modular input folder name renamed based on newer splunk folder name validation. (Github PR [#168](https://github.com/splunk/splunk-sdk-java/pull/168))
+* SDK app collection URL has been updated to v1.1.0 in docker compose file. (Github PR [#168](https://github.com/splunk/splunk-sdk-java/pull/168))
+  * Test files in sdk app collections are modified based on python v3 syntax.
+* Added Saved Search test case based on title. (Github PR [#166](https://github.com/splunk/splunk-sdk-java/pull/166))
+
 ## Version 1.7.1
 
 ### Minor Changes

CHANGELOG.md

@@ -1,7 +1,7 @@
-![Build Status](https://github.com/splunk/splunk-sdk-java/actions/workflows/release.yml/badge.svg?branch=master)
+[![Java SDK Test](https://github.com/splunk/splunk-sdk-java/actions/workflows/test.yml/badge.svg?branch=master)](https://github.com/splunk/splunk-sdk-java/actions/workflows/test.yml)
 # The Splunk Software Development Kit for Java
 
-#### Version 1.7.1
+#### Version 1.8.0
 
 The Splunk Software Development Kit (SDK) for Java contains library code and
 examples designed to enable developers to build applications using Splunk.
@@ -75,7 +75,7 @@ To add the Splunk SDK for Java `.JAR` file as a dependency:
   <dependency>
     <groupId>com.splunk</groupId>
     <artifactId>splunk</artifactId>
-    <version>1.7.1</version>
+    <version>1.8.0</version>
   </dependency>
 </dependencies>
 ```
@@ -109,6 +109,161 @@ To build the documentation for the SDK, it is being automatically generated with
     cd splunk
     mvn javadoc:javadoc
 
+### Usage
+#### Login using username and password
+```java
+import com.splunk.Service;
+import com.splunk.ServiceArgs;
+
+/**
+ * Login using username and password
+ */
+public class SplunkLogin {
+
+    static Service service = null;
+    public static void main(String args[]) {
+        ServiceArgs loginArgs = new ServiceArgs();
+        loginArgs.setPort(8089);
+        loginArgs.setHost("localhost");
+        loginArgs.setScheme("https");
+        loginArgs.setUsername("USERNAME"); // Use your username
+        loginArgs.setPassword("PASSWORD"); // Use your password
+
+        // Initialize the SDK client
+        service = Service.connect(loginArgs);
+    }
+}
+```
+
+#### Login using Session Token
+```java
+import com.splunk.Service;
+import com.splunk.ServiceArgs;
+
+/**
+ * Login using Session token
+ */
+public class SplunkLogin {
+
+    static Service service = null;
+    /**
+     * Session Token.
+     * Actual token length would be longer than this token length.
+     */
+    static String token = "1k_Ostpl6NBe4iVQ5d6I3Ohla_U5";
+    
+    public static void main(String args[]) {
+        ServiceArgs loginArgs = new ServiceArgs();
+        loginArgs.setPort(8089);
+        loginArgs.setHost("localhost");
+        loginArgs.setScheme("https");
+        loginArgs.setToken(String.format("Splunk %s", token));
+
+        // Initialize the SDK client
+        service = Service.connect(loginArgs);
+    }
+}
+```
+* Login using username and password will create Session token internally.
+* Login using Credentials (username & password) OR directly using Session token are similar.
+* In above two approaches, there is one limitation that expiration time of Session token cannot be extended. User has to re-login every time when token expires.
+* To overcome this limitation, **Authentication** token is used instead of Session token.
+* In **Authentication** token, user has a provision to set token expiration time. Splunk allows user to set relative/absolute time for token expiration.
+* In other words, **Authentication** token is configurable whereas Session token cannot be configured.
+
+#### Login using Authentication Token (RECOMMENDED)
+```java
+import com.splunk.Service;
+import com.splunk.ServiceArgs;
+
+/**
+ * Login using Authentication token
+ */
+public class SplunkLogin {
+
+    static Service service = null;
+    /**
+     * Authentication Token.
+     * Actual token length would be longer than this token length.
+     */
+    static String token = "1k_Ostpl6NBe4iVQ5d6I3Ohla_U5";
+    
+    public static void main(String args[]) {
+        ServiceArgs loginArgs = new ServiceArgs();
+        loginArgs.setPort(8089);
+        loginArgs.setHost("localhost");
+        loginArgs.setScheme("https");
+        loginArgs.setToken(String.format("Bearer %s", token));
+
+        // Initialize the SDK client
+        service = Service.connect(loginArgs);
+    }
+}
+```
+
+#### Example of running a simple search by first creating the search job
+```java
+import com.splunk.Job;
+import com.splunk.ResultsReader;
+import com.splunk.ResultsReaderXml;
+import com.splunk.Service;
+import com.splunk.ServiceArgs;
+
+/**
+ * Logged in using Authentication token.
+ * Assuming that authentication token is already created from Splunk web.
+ * Create Job using search creation.
+ * Read results and print _raw fields
+ */
+public class SearchExample {
+
+    static Service service = null;
+
+    /**
+     * Authentication Token.
+     * Actual token length would be longer than this token length.
+     */
+    static String token = "1k_Ostpl6NBe4iVQ5d6I3Ohla_U5";
+    
+    public static void main(String args[]) {
+
+        ServiceArgs loginArgs = new ServiceArgs();
+        loginArgs.setPort(8089);
+        loginArgs.setHost("localhost");
+        loginArgs.setScheme("https");
+        loginArgs.setToken(String.format("Bearer %s", token));
+
+        // Initialize the SDK client
+        service = Service.connect(loginArgs);
+
+        // Run a simple search by first creating the search job
+        Job job = service.getJobs().create("search index=_internal | head 10");
+
+        // Waiting for search results to be ready
+        while (!job.isReady()) {
+            try {
+                Thread.sleep(500); // 500 ms
+            } catch (Exception e) {
+                // Handle exception here.
+            }
+        }
+
+        // Read results
+        try {
+            ResultsReader reader = new ResultsReaderXml(job.getEvents());
+
+            // Iterate over events and print _raw field
+            reader.forEach(event -> System.out.println(event.get("_raw")));
+
+        } catch (Exception e) {
+            // Handle exception here.
+        }
+    }
+}
+```
+
+For more information on authentication using tokens, please visit [Splunk Docs](https://docs.splunk.com/Documentation/Splunk/latest/Security/Setupauthenticationwithtokens).
+
 ### Unit tests
 
 The Splunk SDK for Java includes several unit tests that are run at

README.md

@@ -2,7 +2,7 @@
 
 declare -r scriptDirectory="$(dirname $(readlink -e $0))"
 declare -r scriptName="$(basename $0)"
-declare -r version="1.7.1"
+declare -r version="1.8.0"
 
 if [[ $# -ne 1 ]]; then
     echo 1>&2 "Usage: ${scriptName} {local|staging||production}"

deploy

@@ -9,8 +9,8 @@ deploy \<repository-name>
 
 ##DESCRIPTION
 
-Deploy transmits **target/splunk-1.7.1.jar**, **target/splunk-1.7.1-javadoc.jar**, and
-**target/splunk-1.7.1-sources.jar** to the **local**, **staging**, or **production**
+Deploy transmits **target/splunk-1.8.0.jar**, **target/splunk-1.8.0-javadoc.jar**, and
+**target/splunk-1.8.0-sources.jar** to the **local**, **staging**, or **production**
 maven repository. Repository names are mapped to locations as follows.
 
 | repository-name | location                                                       |
@@ -21,18 +21,18 @@ maven repository. Repository names are mapped to locations as follows.
 
 After deployment you should find this tree structure at the location of your repository
 
-    com/splunk/splunk/1.7.1/
-    ├── splunk-1.7.1-javadoc.jar
-    ├── splunk-1.7.1-javadoc.jar.md5
-    ├── splunk-1.7.1-javadoc.jar.sha1
-    ├── splunk-1.7.1-sources.jar
-    ├── splunk-1.7.1-sources.jar.md5
-    ├── splunk-1.7.1-sources.jar.sha1
-    ├── splunk-1.7.1.jar
-    ├── splunk-1.7.1.jar.md5
-    ├── splunk-1.7.1.jar.sha1
-    ├── splunk-1.7.1.pom
-    ├── splunk-1.7.1.pom.md5
-    └── splunk-1.7.1.pom.sha1
+    com/splunk/splunk/1.8.0/
+    ├── splunk-1.8.0-javadoc.jar
+    ├── splunk-1.8.0-javadoc.jar.md5
+    ├── splunk-1.8.0-javadoc.jar.sha1
+    ├── splunk-1.8.0-sources.jar
+    ├── splunk-1.8.0-sources.jar.md5
+    ├── splunk-1.8.0-sources.jar.sha1
+    ├── splunk-1.8.0.jar
+    ├── splunk-1.8.0.jar.md5
+    ├── splunk-1.8.0.jar.sha1
+    ├── splunk-1.8.0.pom
+    ├── splunk-1.8.0.pom.md5
+    └── splunk-1.8.0.pom.sha1
 
 Verify this structure prior to release.

deploy.md

@@ -2,13 +2,14 @@ version: '3.6'
 
 services:
     splunk:
-        image: "splunk/splunk:8.0"
+        image: "splunk/splunk:latest"
         container_name: splunk
         environment:
             - SPLUNK_START_ARGS=--accept-license
             - SPLUNK_HEC_TOKEN=11111111-1111-1111-1111-1111111111113
             - SPLUNK_PASSWORD=changed!
-            - SPLUNK_APPS_URL=https://github.com/splunk/sdk-app-collection/releases/download/v1.0.0/sdk-app-collection.tgz
+            - SPLUNK_APPS_URL=https://github.com/splunk/sdk-app-collection/releases/download/v1.1.0/sdkappcollection.tgz
+            - JAVA_VERSION=openjdk:8
         ports:
             - 8000:8000
             - 8088:8088

docker-compose.yml

@@ -8,7 +8,7 @@
     <parent>
         <artifactId>splunk-sdk-java</artifactId>
         <groupId>com.splunk</groupId>
-        <version>1.0.0</version>
+        <version>1.0.1</version>
     </parent>
 
     <build>
@@ -21,6 +21,7 @@
                     <skipTests>true</skipTests>
                 </configuration>
             </plugin>
+            <!-- Deploy plugin is overridden here because we are skipping deployment in case of examples module. -->
             <plugin>
                 <groupId>org.apache.maven.plugins</groupId>
                 <artifactId>maven-deploy-plugin</artifactId>
@@ -36,7 +37,7 @@
         <dependency>
             <groupId>com.splunk</groupId>
             <artifactId>splunk</artifactId>
-            <version>1.7.1</version>
+            <version>1.8.0</version>
             <scope>provided</scope>
         </dependency>
         <dependency>

examples/pom.xml

@@ -6,7 +6,7 @@
     <modelVersion>4.0.0</modelVersion>
 
     <properties>
-        <version.number>1.7.1</version.number>
+        <version.number>1.8.0</version.number>
         <maven.resources.overwrite>true</maven.resources.overwrite>
         <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
         <maven.compiler.source>8</maven.compiler.source>
@@ -15,7 +15,7 @@
 
     <groupId>com.splunk</groupId>
     <artifactId>splunk-sdk-java</artifactId>
-    <version>1.0.0</version>
+    <version>1.0.1</version>
     <packaging>pom</packaging>
     <name>Splunk SDK for Java</name>
     <url>https://dev.splunk.com/enterprise/docs/devtools/java/sdk-java</url>
@@ -31,12 +31,6 @@
             <artifactId>opencsv</artifactId>
             <version>2.3</version>
         </dependency>
-        <dependency>
-            <groupId>org.apache.maven.plugins</groupId>
-            <artifactId>maven-deploy-plugin</artifactId>
-            <version>3.0.0-M1</version>
-            <type>maven-plugin</type>
-        </dependency>
     </dependencies>
     <modules>
         <module>splunk</module>