<commit_before># Samples Format
## Table of Contents
  * [Java Version](#java-version)
  * [Specific Goals](#specific-goals)
  * [Testing](#testing)
    * [Testing Setup](#testing-setup)
    * [Running Locally](#running-locally)
    * [Gradle Specifics](#gradle-specifics)
  * [Format Guidelines](#format-guidelines)
    * [Location](#project-location)
    * [Dependencies](#project-dependencies)
    * [Configuration](#project-configuration)
    * [Setup](#project-setup)
  * [Code](#code)
    * [Arrange, Act, Assert](#arrange-act-assert)
    * [Style](#style)
    * [Linting](#linting)
    * [Package Names](#package-names)
    * [Class Structure]()
    * [Function Comment]()
    * [Function Structure]()
    * [Exception Handling]()
    * [Client Initialization](#client-initialization)
    * [Command-Line Arguments](#command-line-arguments)
  * [Modern Java](#modern-java)
    * [Lambdas](#lambdas)
    * [Streams](#streams)
    * [Parallel Streams](#parallel-streams)
  * [Additional Best Practices](#additional-best-practices)
    * [Time](#time)
    * [Logging](#logging)

This doc maintains an outline for 'snippet' samples specific to Java. Currently, the java canonical
samples in this format are located 
[here](/tree/master/dlp/src/main/java/dlp/snippets).

Larger sample applications should attempt to follow many of these guidelines as well, but some may
be ignored or waived as there can be many structural differences between applications and snippets.

## Java Version

All samples should be written to run on both Java 8 and Java 11, samples that don't run on Java 8 
should clearly says so in their README and specifically set Java 11 in their `pom`.  There should be
a clear reason why Java 8 isn't supported.

## Specific Goals
This sample format is intended to help enforce some specific goals in our samples. Even if not 
specifically mentioned in the format, samples should make best-effort attempts in the following:

* __Copy-paste-runnable__ - Users should be able to copy and paste the code into their own
  environments and run with as few and transparent modifications as possible. Samples should be as
  easy for a user to run as possible.
  
* __Teach through code__ - samples should teach users both how and why specific best practices
  should be implemented and performed when interacting with our services.
  
* __Idiomatic__ - examples should make best attempts to remain idiomatic and encourage good 
  practices that are specific to a language or practice. 

## Build Tools

All new samples should build and run integration tests with [Maven](https://maven.apache.org/).
[Gradle](https://gradle.org/) support is optional as we don't yet have regular testing.

## Testing
Any infrastructure required to run the test (such as a GCS bucket or a Cloud SQL instance) should
be passed in as an environment variable. Tests should clearly indicated which environment variables
are required for the tests to pass.

Resources required outside of this infrastructure should be generated and cleaned up (even on 
failures) as part of the test suite. Please note that tests should run successfully in parallel, 
and UUIDs should be used to prevent conflicts.

Snippets should have integration tests that should verify the snippet compiles and runs
successfully. Tests should only verify that the sample itself is interacting with the service
correctly - it is an explicit non goal for tests to verify that API is performing correctly.
Because of this, mocks for external services are strongly discouraged.

* Test Library: [JUnit4](https://junit.org/junit4/)
* Test Runner: [Maven Failsafe plugin](https://maven.apache.org/surefire/maven-failsafe-plugin/)
and [Maven Surefire plugin](https://maven.apache.org/surefire/maven-surefire-plugin/).

As an example, the following test code shows how we test a region tag (region tags are tools Google
uses to identify sections of the snippets to be highlighted in documentation) called `region_tag`:
```java
package com.google.example;

import org.junit.Assert;
import org.junit.Before;
import org.junit.Test;
import org.junit.runner.RunWith;
import org.junit.runners.JUnit4;

/**
 * Store region_tag in test method name, camel-cased
 */ 
@RunWith(JUnit4.class)
public class SomeClassTest {
  @Test public void regionTag_shouldPass() throws Exception { }

  @Test public void regionTag_shouldFail() throws Exception {
    Assert.fail("should fail");
  }
}
```
You will note:
 * underscores (`_`) are used in test method names to separate blocks of `camelCase` text
 * these blocks denote _region tags_, which serve as unique IDs for snippets in a given repository
 * `camelCase` blocks beginning with `should` or `does` are **not** region tags - instead, they
 simply describe the test being run

It is also possible to use annotations to provide info for `region_tag` if you need to do this,
please contact one of the repo admins.

### Testing Setup
Most samples require a GCP project and billing account. Keep the following in
mind when setting up tests.

* **Environment variables**  
  Minimize additional environment variables that need to be set to run the tests.
  If you do require additional environment variables, they should be added to
  [run_tests.sh](/java-docs-samples/blob/master/.kokoro/tests/run_tests.sh).

  Existing environment variables include:
  * `GOOGLE_APPLICATION_CREDENTIALS`
  * `GOOGLE_CLOUD_PROJECT`
  * `PROJECT_ID`

* **API library**  
  If an API needs to be enabled in the testing project, add this information to the
  directory's README and to the comments in the PR. If there is no README.md file, add one
  in your PR.

* **IAM**
  Some API's require that the service account have some additional capibilities, these should also
  be mentioned in both the PR and the README.

* **Cloud resources**  
  Most Java samples create the Cloud resources that they need to run. If this
  is resource intensive or not possible, add instructions to the directory's README.md file<commit_msg>Fix 2 URL's (#2514)<commit_after># Samples Format
## Table of Contents
  * [Java Version](#java-version)
  * [Specific Goals](#specific-goals)
  * [Testing](#testing)
    * [Testing Setup](#testing-setup)
    * [Running Locally](#running-locally)
    * [Gradle Specifics](#gradle-specifics)
  * [Format Guidelines](#format-guidelines)
    * [Location](#project-location)
    * [Dependencies](#project-dependencies)
    * [Configuration](#project-configuration)
    * [Setup](#project-setup)
  * [Code](#code)
    * [Arrange, Act, Assert](#arrange-act-assert)
    * [Style](#style)
    * [Linting](#linting)
    * [Package Names](#package-names)
    * [Class Structure]()
    * [Function Comment]()
    * [Function Structure]()
    * [Exception Handling]()
    * [Client Initialization](#client-initialization)
    * [Command-Line Arguments](#command-line-arguments)
  * [Modern Java](#modern-java)
    * [Lambdas](#lambdas)
    * [Streams](#streams)
    * [Parallel Streams](#parallel-streams)
  * [Additional Best Practices](#additional-best-practices)
    * [Time](#time)
    * [Logging](#logging)

This doc maintains an outline for 'snippet' samples specific to Java. Currently, the java canonical
samples in this format are located 
[here](../../tree/master/dlp/src/main/java/dlp/snippets).

Larger sample applications should attempt to follow many of these guidelines as well, but some may
be ignored or waived as there can be many structural differences between applications and snippets.

## Java Version

All samples should be written to run on both Java 8 and Java 11, samples that don't run on Java 8 
should clearly says so in their README and specifically set Java 11 in their `pom`.  There should be
a clear reason why Java 8 isn't supported.

## Specific Goals
This sample format is intended to help enforce some specific goals in our samples. Even if not 
specifically mentioned in the format, samples should make best-effort attempts in the following:

* __Copy-paste-runnable__ - Users should be able to copy and paste the code into their own
  environments and run with as few and transparent modifications as possible. Samples should be as
  easy for a user to run as possible.
  
* __Teach through code__ - samples should teach users both how and why specific best practices
  should be implemented and performed when interacting with our services.
  
* __Idiomatic__ - examples should make best attempts to remain idiomatic and encourage good 
  practices that are specific to a language or practice. 

## Build Tools

All new samples should build and run integration tests with [Maven](https://maven.apache.org/).
[Gradle](https://gradle.org/) support is optional as we don't yet have regular testing.

## Testing
Any infrastructure required to run the test (such as a GCS bucket or a Cloud SQL instance) should
be passed in as an environment variable. Tests should clearly indicated which environment variables
are required for the tests to pass.

Resources required outside of this infrastructure should be generated and cleaned up (even on 
failures) as part of the test suite. Please note that tests should run successfully in parallel, 
and UUIDs should be used to prevent conflicts.

Snippets should have integration tests that should verify the snippet compiles and runs
successfully. Tests should only verify that the sample itself is interacting with the service
correctly - it is an explicit non goal for tests to verify that API is performing correctly.
Because of this, mocks for external services are strongly discouraged.

* Test Library: [JUnit4](https://junit.org/junit4/)
* Test Runner: [Maven Failsafe plugin](https://maven.apache.org/surefire/maven-failsafe-plugin/)
and [Maven Surefire plugin](https://maven.apache.org/surefire/maven-surefire-plugin/).

As an example, the following test code shows how we test a region tag (region tags are tools Google
uses to identify sections of the snippets to be highlighted in documentation) called `region_tag`:
```java
package com.google.example;

import org.junit.Assert;
import org.junit.Before;
import org.junit.Test;
import org.junit.runner.RunWith;
import org.junit.runners.JUnit4;

/**
 * Store region_tag in test method name, camel-cased
 */ 
@RunWith(JUnit4.class)
public class SomeClassTest {
  @Test public void regionTag_shouldPass() throws Exception { }

  @Test public void regionTag_shouldFail() throws Exception {
    Assert.fail("should fail");
  }
}
```
You will note:
 * underscores (`_`) are used in test method names to separate blocks of `camelCase` text
 * these blocks denote _region tags_, which serve as unique IDs for snippets in a given repository
 * `camelCase` blocks beginning with `should` or `does` are **not** region tags - instead, they
 simply describe the test being run

It is also possible to use annotations to provide info for `region_tag` if you need to do this,
please contact one of the repo admins.

### Testing Setup
Most samples require a GCP project and billing account. Keep the following in
mind when setting up tests.

* **Environment variables**  
  Minimize additional environment variables that need to be set to run the tests.
  If you do require additional environment variables, they should be added to
  [run_tests.sh](../../blob/master/.kokoro/tests/run_tests.sh).

  Existing environment variables include:
  * `GOOGLE_APPLICATION_CREDENTIALS`
  * `GOOGLE_CLOUD_PROJECT`
  * `PROJECT_ID`

* **API library**  
  If an API needs to be enabled in the testing project, add this information to the
  directory's README and to the comments in the PR. If there is no README.md file, add one
  in your PR.

* **IAM**
  Some API's require that the service account have some additional capibilities, these should also
  be mentioned in both the PR and the README.

* **Cloud resources**  
  Most Java samples create the Cloud resources that they need to run. If this
  is resource intensive or not possible, add instructions to the directory's README.md file
{'fraction_non_alphanumeric': 0.08152536715620828, 'fraction_numerical': 0.002253004005340454, 'mean_word_length': 4.310146211785556, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 10, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3343433', 'n_tokens_mistral': 3327, 'n_tokens_neox': 3132, 'n_words': 1462}