<commit_before>[![Build Status](https://travis-ci.org/PerimeterX/perimeterx-java-sdk.svg?branch=master)](https://travis-ci.org/PerimeterX/perimeterx-java-sdk)
[![Javadocs](http://www.javadoc.io/badge/com.perimeterx/perimeterx-sdk.svg?color=brightgreen)](http://www.javadoc.io/doc/com.perimeterx/perimeterx-sdk)


![image](http://media.marketwire.com/attachments/201604/34215_PerimeterX_logo.jpg)

[PerimeterX](http://www.perimeterx.com) Java SDK
=============================================================

Table of Contents
-----------------

-   [Usage](#usage)
  *   [Prerequisites](#prerequisites)
  *   [Installation](#installation)
  *   [Basic Usage Example](#basic-usage)
-   [Configuration](#configuration)
  *   [Blocking Score](#blocking-score)
  *   [Custom Block Action](#custom-block)
  *   [Enable/Disable Captcha](#captcha-support)
  *   [Extracting Real IP Address](#real-ip)
  *   [Filter Sensitive Headers](#sensitive-headers)
  *   [API Timeout Milliseconds](#api-timeout)
  *   [Send Page Activities](#send-page-activities)

<a name="prerequisites"></a> Prerequisites
----------------------------

##### JDK:
Use `jdk 1.7` or higher.
##### Unlimited Strength Jurisdiction Policy:

Make sure your JDK supports unlimited key length.

If the SDK is throwing `Unlimited Strength Jurisdiction Policy` assertion errors on startup, follow the instructions below: 

1. Download `JCE` for [jdk17](http://www.oracle.com/technetwork/java/javase/downloads/jce-7-download-432124.html) or for [jdk18](http://www.oracle.com/technetwork/java/javase/downloads/jce8-download-2133166.html).
2. Replace `local_policy.jar` and `US_export_policy.jar` in your `$JAVA_HOME/jre/lib/security/` with those you have downloaded.
3. Run your project again and the `Unlimited Strength Jurisdiction Policy` error should no appear.

<a name="installation"></a> Installation
----------------------------------------

####Maven:

* Add `perimeterx-sdk` to `pom.xml`:

```xml
<dependency>
	<groupId>com.perimeterx</groupId>
   <artifactId>perimeterx-sdk</artifactId>
   <version>${VERSION}</version>
</dependency>
```

####gradle:

* Add `perimeterx-sdk` to your `build.gradle`:

```groovy
compile group: 'com.perimeterx', name: 'perimeterx-sdk', version: '${VERSION}'
```



### <a name="basic-usage"></a> Basic Usage Example

```java
// Create configuration object
PXConfiguration pxConfiguration = new PXConfiguration.Builder()
	.cookieKey(COOKIE_KEY)
	.authToken(AUTH_TOKEN)
	.appId(APP_ID)
	.blockingScore(SCORE)
	.build();

// Get instance
PerimeterX px = PerimeterX.getInstance(pxConfiguration);

// Inside the request / Filter
@Override
protected void doGet(HttpServletRequest req, HttpservletResponse resp) throws ServletException, IOExcption {
...
	px.pxVerify(req, new HttpServletResponseWrapper(resp);
...
}

```
### <a name="configuration"></a> Configuration Options

#### Configuring Required Parameters

Configuration options are set in `PXConfiguration`

#### Required Parameters:

- appId
- cookieKey
- authToken

##### <a name="blocking-score"></a> Changing the Minimum Score for Blocking

**default:** 70

```java
PXConfiguration pxConfiguration = new PXConfiguration.Builder()
	...
	.blockingScore(50)
	...
	.build();
```

#### <a name="custom-block"></a> Custom Blocking Actions
Setting a custom block handler customizes is done by implementing the `BlockHandler` interface and set the `blockHandler` field in `PerimeterX` object and `pxVerify` method will run `blockHandler.handleBlocking`.

**default:**  The `DefaultBlockHandler` supplied in this SDK returns an HTTP status code 403 and serves the
PerimeterX block page.

###### Examples

**Serve a Custom HTML Page**

```java
public class LoggerBlockHandler implements BlockHandler {

	public void handleBlocking(PXContext context, HttpServletResponseWrapper responseWrapper) {
		Systm.out.Println("Loggin request " + responseWrapper);
	}
}
```

#### <a name="captcha-support"></a>Enable/disable captcha in the block page

By enabling captcha support, a captcha will be served as part of the block page giving real users the ability to answer, get score clean up and be passed to the requested page.

**default: true**

```java
PXConfiguration pxConfiguration = new PXConfiguration.Builder()
	...
	.captchaEnabled(true)
	...
	.build();
```

##### <a name="real-ip"></a>Extracting the Real User IP Address From HTTP Headers or by defining a function

> Note: IP extraction according to your network setup is important. It is common to have a load balancer/proxy on top of your applications. In this case, the PerimeterX module will send an internal IP as the user's. In order to perform processing and detection for server-to-server calls, the PerimeterX module needs the real user IP.

The user IP can be passed to the PerimeterX module by implementing the `IPProvider` interface and configuring it on the `PerimeterX` object.


This SDK provids two implementations for this:

- `RemoteAddressIPProvider` (deault) which extracts the Remote address from a raw servlet request.
- `IPByHeaderProvider` which can be constructed with a header key, and when applied, will extract this value haeder as the true IP.

You can set your own `IPProvider`:

```java
// java < 8
px.setIpProvider(new IPProvider() {
    public String getRequestIP(HttpServletRequest request) {
    	return "127.0.0.1";
    }
});

// java >= 8
px.setIpProvider(httpRequest -> "127.0.0.1");
```

#### <a name="sensitive-headers"></a> Filter sensitive headers

A user can define a list of sensitive headers a user wants to prevent from being send to PerimeterX servers. Filtering the cookie header for privacy is set by default and will be overriden if a user sets the configuration.

**default: cookie, cookies**

```java
PXConfiguration pxConfiguration = new PXConfiguration.Builder()
	...
	.addSensitiveHeader("Authorization")
	.addSensitiveHeader("Secret-Header")
	...
	.build()
```

#### <a name="api-timeout"></a>API Timeout Milliseconds

Timeout in seconds (float) to wait for the PerimeterX server API response.
The API is called when the risk cookie does not exist, or is expired or
invalid.

**default:** 1000 Miliseconds

```java
PXConfiguration pxConfiguration = new PXConfiguration.Builder()
	...
	.apiTimeout(2000)
	...
	.build()
```

#### <a name="send-page-activities"></a> Send Page Activities

A Boolean flag to enable or disable sending activities and metrics to
PerimeterX on each page request. Enabling this feature will provide data
that populates the PerimeterX portal with valuable information, such as
amount of requests blocked and API usage statistics.

**default:** false

```java
PXConfiguration pxConfiguration = new PXConfiguration.Builder()
	...
	.sendPageActivities(true)
	...
	.build()
```
<commit_msg>EN-2672 Replaced README logo<commit_after>[![Build Status](https://travis-ci.org/PerimeterX/perimeterx-java-sdk.svg?branch=master)](https://travis-ci.org/PerimeterX/perimeterx-java-sdk)
[![Javadocs](http://www.javadoc.io/badge/com.perimeterx/perimeterx-sdk.svg?color=brightgreen)](http://www.javadoc.io/doc/com.perimeterx/perimeterx-sdk)


![image](https://s.perimeterx.net/logo.png)

[PerimeterX](http://www.perimeterx.com) Java SDK
=============================================================

Table of Contents
-----------------

-   [Usage](#usage)
  *   [Prerequisites](#prerequisites)
  *   [Installation](#installation)
  *   [Basic Usage Example](#basic-usage)
-   [Configuration](#configuration)
  *   [Blocking Score](#blocking-score)
  *   [Custom Block Action](#custom-block)
  *   [Enable/Disable Captcha](#captcha-support)
  *   [Extracting Real IP Address](#real-ip)
  *   [Filter Sensitive Headers](#sensitive-headers)
  *   [API Timeout Milliseconds](#api-timeout)
  *   [Send Page Activities](#send-page-activities)

<a name="prerequisites"></a> Prerequisites
----------------------------

##### JDK:
Use `jdk 1.7` or higher.
##### Unlimited Strength Jurisdiction Policy:

Make sure your JDK supports unlimited key length.

If the SDK is throwing `Unlimited Strength Jurisdiction Policy` assertion errors on startup, follow the instructions below: 

1. Download `JCE` for [jdk17](http://www.oracle.com/technetwork/java/javase/downloads/jce-7-download-432124.html) or for [jdk18](http://www.oracle.com/technetwork/java/javase/downloads/jce8-download-2133166.html).
2. Replace `local_policy.jar` and `US_export_policy.jar` in your `$JAVA_HOME/jre/lib/security/` with those you have downloaded.
3. Run your project again and the `Unlimited Strength Jurisdiction Policy` error should no appear.

<a name="installation"></a> Installation
----------------------------------------

####Maven:

* Add `perimeterx-sdk` to `pom.xml`:

```xml
<dependency>
	<groupId>com.perimeterx</groupId>
   <artifactId>perimeterx-sdk</artifactId>
   <version>${VERSION}</version>
</dependency>
```

####gradle:

* Add `perimeterx-sdk` to your `build.gradle`:

```groovy
compile group: 'com.perimeterx', name: 'perimeterx-sdk', version: '${VERSION}'
```



### <a name="basic-usage"></a> Basic Usage Example

```java
// Create configuration object
PXConfiguration pxConfiguration = new PXConfiguration.Builder()
	.cookieKey(COOKIE_KEY)
	.authToken(AUTH_TOKEN)
	.appId(APP_ID)
	.blockingScore(SCORE)
	.build();

// Get instance
PerimeterX px = PerimeterX.getInstance(pxConfiguration);

// Inside the request / Filter
@Override
protected void doGet(HttpServletRequest req, HttpservletResponse resp) throws ServletException, IOExcption {
...
	px.pxVerify(req, new HttpServletResponseWrapper(resp);
...
}

```
### <a name="configuration"></a> Configuration Options

#### Configuring Required Parameters

Configuration options are set in `PXConfiguration`

#### Required Parameters:

- appId
- cookieKey
- authToken

##### <a name="blocking-score"></a> Changing the Minimum Score for Blocking

**default:** 70

```java
PXConfiguration pxConfiguration = new PXConfiguration.Builder()
	...
	.blockingScore(50)
	...
	.build();
```

#### <a name="custom-block"></a> Custom Blocking Actions
Setting a custom block handler customizes is done by implementing the `BlockHandler` interface and set the `blockHandler` field in `PerimeterX` object and `pxVerify` method will run `blockHandler.handleBlocking`.

**default:**  The `DefaultBlockHandler` supplied in this SDK returns an HTTP status code 403 and serves the
PerimeterX block page.

###### Examples

**Serve a Custom HTML Page**

```java
public class LoggerBlockHandler implements BlockHandler {

	public void handleBlocking(PXContext context, HttpServletResponseWrapper responseWrapper) {
		Systm.out.Println("Loggin request " + responseWrapper);
	}
}
```

#### <a name="captcha-support"></a>Enable/disable captcha in the block page

By enabling captcha support, a captcha will be served as part of the block page giving real users the ability to answer, get score clean up and be passed to the requested page.

**default: true**

```java
PXConfiguration pxConfiguration = new PXConfiguration.Builder()
	...
	.captchaEnabled(true)
	...
	.build();
```

##### <a name="real-ip"></a>Extracting the Real User IP Address From HTTP Headers or by defining a function

> Note: IP extraction according to your network setup is important. It is common to have a load balancer/proxy on top of your applications. In this case, the PerimeterX module will send an internal IP as the user's. In order to perform processing and detection for server-to-server calls, the PerimeterX module needs the real user IP.

The user IP can be passed to the PerimeterX module by implementing the `IPProvider` interface and configuring it on the `PerimeterX` object.


This SDK provids two implementations for this:

- `RemoteAddressIPProvider` (deault) which extracts the Remote address from a raw servlet request.
- `IPByHeaderProvider` which can be constructed with a header key, and when applied, will extract this value haeder as the true IP.

You can set your own `IPProvider`:

```java
// java < 8
px.setIpProvider(new IPProvider() {
    public String getRequestIP(HttpServletRequest request) {
    	return "127.0.0.1";
    }
});

// java >= 8
px.setIpProvider(httpRequest -> "127.0.0.1");
```

#### <a name="sensitive-headers"></a> Filter sensitive headers

A user can define a list of sensitive headers a user wants to prevent from being send to PerimeterX servers. Filtering the cookie header for privacy is set by default and will be overriden if a user sets the configuration.

**default: cookie, cookies**

```java
PXConfiguration pxConfiguration = new PXConfiguration.Builder()
	...
	.addSensitiveHeader("Authorization")
	.addSensitiveHeader("Secret-Header")
	...
	.build()
```

#### <a name="api-timeout"></a>API Timeout Milliseconds

Timeout in seconds (float) to wait for the PerimeterX server API response.
The API is called when the risk cookie does not exist, or is expired or
invalid.

**default:** 1000 Miliseconds

```java
PXConfiguration pxConfiguration = new PXConfiguration.Builder()
	...
	.apiTimeout(2000)
	...
	.build()
```

#### <a name="send-page-activities"></a> Send Page Activities

A Boolean flag to enable or disable sending activities and metrics to
PerimeterX on each page request. Enabling this feature will provide data
that populates the PerimeterX portal with valuable information, such as
amount of requests blocked and API usage statistics.

**default:** false

```java
PXConfiguration pxConfiguration = new PXConfiguration.Builder()
	...
	.sendPageActivities(true)
	...
	.build()
```

{'fraction_non_alphanumeric': 0.1427195970967264, 'fraction_numerical': 0.00896163531328692, 'mean_word_length': 4.554504319210202, 'pattern_counts': {'":': 0, '<': 65, '<?xml version=': 0, '>': 69, 'https://': 5, 'lorem ipsum': 0, 'www.': 10, 'xml': 4}, 'pii_count': 4, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 12, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1127434', 'n_tokens_mistral': 4157, 'n_tokens_neox': 3902, 'n_words': 1285}