Skip to content

Commit cadb863

Browse files
averikitschaverikitsch
authored
Merge branch 'master' into patch-1
2 parents 558b2e7 + 7325051 commit cadb863

File tree

357 files changed

+13694
-5002
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

357 files changed

+13694
-5002
lines changed

‎.kokoro/tests/run_tests.sh

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -56,6 +56,7 @@ if [[ "$SCRIPT_DEBUG" != "true" ]]; then
5656
source "${KOKORO_GFILE_DIR}/aws-secrets.sh"
5757
source "${KOKORO_GFILE_DIR}/storage-hmac-credentials.sh"
5858
source "${KOKORO_GFILE_DIR}/dlp_secrets.txt"
59+
source "${KOKORO_GFILE_DIR}/bigtable_secrets.txt"
5960
# Activate service account
6061
gcloud auth activate-service-account \
6162
--key-file="$GOOGLE_APPLICATION_CREDENTIALS" \

‎CONTRIBUTING.md

Lines changed: 1 addition & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -40,13 +40,7 @@ accept your pull requests.
4040

4141
## Contributing a new sample
4242

43-
1. App Engine Standard samples all go into `/appengine` (java 7) or `/java8-appengine` (Java 8) (if you're contributing a group of samples,
44-
please put the App Engine Standard sample into `/appengine` and provide a link in both `README.md`'s for
45-
the project for the additional sample.
46-
47-
1. App Engine Flexible samples all go into `/flexible`
48-
49-
1. Technology samples go into the project root.
43+
1. See the [SAMPLE_FORMAT.md](SAMPLE_FORMAT.md) for guidelines on the preferred sample format.
5044

5145

5246
## Build Tools

‎README.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@ This is a repository that contains java code snippets on [Cloud Platform Documen
1313
Technology Samples:
1414

1515
* [Bigquery](bigquery)
16+
* [Data Catalog](datacatalog)
1617
* [Datastore](datastore)
1718
* [Endpoints](endpoints)
1819
* [Identity-Aware Proxy](iap)

‎SAMPLE_FORMAT.md

Lines changed: 132 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,132 @@
1+
# Samples Format
2+
3+
This doc maintains an outline for 'snippet' samples specific to Java. Currently, the java canonical
4+
samples in this format are located
5+
[here](https://github.com/GoogleCloudPlatform/java-docs-samples/tree/master/dlp/src/main/java/dlp/snippets).
6+
7+
8+
## Specific Goals
9+
This sample format is intended to help enforce some specific goals in our samples. Even if not
10+
specifically mentioned in the format, samples should make best-effort attempts in the following:
11+
12+
* __Easily runnable__ - samples should be as easy for a user to run as possible. Users should be
13+
able to copy and paste the code into their own environments and run with as few and transparent
14+
modifications as possible.
15+
16+
* __Teach through code__ - samples should teach users how and why specific best practices should
17+
be implemented and performed when interacting with our services.
18+
19+
* __Idiomatic__ - examples should make best attempts to remain idiomatic and encourage good
20+
practices that are specific to a language or practice.
21+
22+
## Format Guidelines
23+
24+
### Project Location
25+
Samples should be in a project folder under the name of the product the snippet represents.
26+
Additional sub folders should be used to differentiate groups of samples. Folder and package paths
27+
should try to avoid containing unnecessary folders to allow users to more easily navigate to the
28+
snippets themselves.
29+
30+
### Project Dependencies
31+
Project should have a `pom.xml` that is readably formatted, declares a parent pom as shown below,
32+
and declares all dependencies needed for the project. Best attempts should be made to minimize
33+
necessary dependencies without sacrificing the idiomatic practices.
34+
35+
```xml
36+
<!--
37+
The parent pom defines common style checks and testing strategies for our samples.
38+
Removing or replacing it should not affect the execution of the samples in anyway.
39+
-->
40+
<parent>
41+
<groupId>com.google.cloud.samples</groupId>
42+
<artifactId>shared-configuration</artifactId>
43+
<version>SPECIFY_LATEST_VERSION</version>
44+
</parent>
45+
```
46+
47+
### Project Setup
48+
The README.md should contain instructions for the user to get the samples operable. Ideally, steps
49+
such as project or resource setup should be links to Cloud Documentation. This is to reduce
50+
duplicate instructions and README maintenance in the future.
51+
52+
### Sample Structure
53+
Each snippet should be be contained in its own file, within a class with a name descriptive of
54+
the snippet and a similarly named function. Region tags should start below the package, but should
55+
include the class and any imports in full. Additional functions can be used if it improves
56+
readability of the sample.
57+
58+
### Function Parameters
59+
Function parameters should be limited to what is absolutely required for testing. For example,
60+
project specific information (such as `projectId`) or a `filePath` for an external file are
61+
allowed. A parameter for the type of a file or a specific action is not.
62+
63+
Any declared function parameters should include a commented out example of how that parameter could
64+
be declared. This provides both an example of how to derive the variables and what information they
65+
should represent.
66+
67+
### Function Return Type
68+
The function in the snippet should not return any value. Instead, they should print the results of
69+
actions to the console to be validated later.
70+
71+
### Exception Handling
72+
The snippet should show how to correctly handle Exceptions that occur during the snippet. Top level
73+
exceptions can be handled by logging the exception to `System.out.println`. If the exception is
74+
something the user may commonly encounter, include a comment explaining how to avoid or handle
75+
correctly.
76+
77+
Example:
78+
```java
79+
try {
80+
// Do something
81+
} catch (IllegalArgumentException e) {
82+
// IllegalArgumentException's are thrown when an invalid argument has been passed to a function.
83+
// This error should be logged to that the root cause can be debugged and prevented in the future.
84+
System.out.println("Error during functionName: \n" + e.toString());
85+
}
86+
```
87+
88+
### Client Initialization
89+
The preferred style for initialization is to use a try-with-resources statement with a comment
90+
clarifying how to handle multiple requests and clean up instructions.
91+
92+
Example:
93+
```java
94+
// Initialize client that will be used to send requests. This client only needs to be created
95+
// once, and can be reused for multiple requests. After completing all of your requests, call
96+
// the "close" method on the client to safely clean up any remaining background resources.
97+
try (DlpServiceClient dlp = DlpServiceClient.create()) {
98+
// Do something
99+
} catch (Exception e) {
100+
System.out.println("Error during functionName: \n" + e.toString());
101+
}
102+
```
103+
104+
### Arrange, Act, Assert
105+
Samples should generally follow the following outline:
106+
* _Arrange_ - Create and configure the components for the request. Avoid nesting these components,
107+
as often they use Builders which can hinder readibility.
108+
* _Act_ - Send the request and receive the response.
109+
* _Assert_ - Verify the call was successful or that the response is correct. This is often done by
110+
print contents of the response to stdout.
111+
112+
### Testing
113+
Snippets should have tests that should verify the snippet works and compiles correctly. Creating
114+
mocks for these tests are optional. These tests should capture output created by the snippet to
115+
verify that it works correctly. See the tests in the cannoncial for an example of how to do this
116+
correctly.
117+
118+
### External Resources
119+
Use of environment variables over system properties is strongly preferred for configuration.
120+
121+
Any additional files required should be stored in `src/test/resources`.
122+
123+
## Additional Best Practices
124+
125+
The following are some general Java best practices that should be followed in samples to remain
126+
idiomatic.
127+
128+
### Time
129+
Use the `java.time` package when dealing with units of time in some manner.
130+
131+
### Logging
132+
Use `java.util.logging` for consistent logging in web applications.

‎appengine-java11/README.md

Lines changed: 43 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,15 @@
11
# Google App Engine Standard Environment Samples for Java 11
22

3-
<a href="https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/ludoch/samples&page=editor&open_in_editor=appengine-java11/README.md">
3+
<a href="https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/GoogleCloudPlatform/java-docs-samples&page=editor&open_in_editor=appengine-java11/README.md">
44
<img alt="Open in Cloud Shell" src ="http://gstatic.com/cloudssh/images/open-btn.png"></a>
55

66
This is a repository that contains Java code samples for [Google App Engine][ae-docs]
77
standard Java 11 environment.
88

9-
[ae-docs]: https://cloud.google.com/appengine/docs/java/
9+
[ae-docs]: https://cloud.google.com/appengine/docs/standard/java11/
1010

1111
## Prerequisites
1212

13-
**Private Alpha**
14-
To access the Java 11 Google App Engine standard runtime, you'll need to apply
15-
to become part of the App Engine [Alpha program](https://docs.google.com/forms/d/e/1FAIpQLSf5uE5eknJjFEmcVBI6sMitBU0QQ1LX_J7VrA_OTQabo6EEEw/viewform).
16-
17-
1813
### Download Maven
1914

2015
These samples use the [Apache Maven][maven] build system. Before getting
@@ -51,11 +46,49 @@ To switch to an Open JDK 11 in a Cloud shell session, you can use:
5146
export JAVA_HOME=/usr/lib/jvm/java-11-openjdk-amd64
5247
```
5348

54-
### appengine-simple-jetty-main
49+
## Java 11 runtime
50+
51+
The simplest way to deploy to App Engine Java 11 is using an executable [Uber JAR][uber-jar]. App Engine will automatically configure the `entrypoint` to run the JAR file.
52+
53+
* [`springboot-helloworld`](springboot-helloworld): Build a fat JAR with Spring Boot
54+
* [`http-server`](http-server): Build a JAR using the Maven JAR Plugin
55+
56+
In addition, App Engine allows you to execute the `java` command directly in the `app.yaml` `entrypoint` field, so you can further customize your app's startup.
57+
58+
* [`custom-entrypoint`](custom-entrypoint): Run a simple server
59+
* [`helloworld-servlet`](helloworld-servlet): Run a WAR package servlet
60+
61+
With a custom `entrypoint`, you can also construct and package your application as a thin JAR (or an exploded JAR). When you deploy your application, the App Engine plugin will only upload the files that changed, rather than the entire [Uber JAR][uber-jar] package.
62+
63+
For more information on the Java 11 runtime, see
64+
[Building an App](https://cloud.google.com/appengine/docs/standard/java11/building-app/)
65+
and [Migrating your App Engine app from Java 8 to Java 11](https://cloud.google.com/appengine/docs/standard/java11/java-differences).
66+
5567

56-
[appengine-simple-jetty-main](appengine-simple-jetty-main) is a shared artifact
68+
### Servlet Runtime
69+
70+
To migrate to the Java 11 runtime, your application must have a
71+
`Main` class that starts a web server.
72+
[`appengine-simple-jetty-main`](appengine-simple-jetty-main) is a shared artifact
5773
that provides a Jetty Web Server for the servlet based runtime. Packaged as a
5874
jar, the Main Class will load a war file, passed as an argument, as the
5975
context root of the web application listening to port 8080.
6076
Some samples create a `<sample-name>.war` which is used as an argument in the
61-
App Engine app.yaml entrypoint field.
77+
App Engine `app.yaml` entrypoint field.
78+
79+
80+
### App Engine Staging Directory
81+
82+
The App Engine Plugin will stage all the files to upload into App Engine
83+
runtime in `${build.directory}/appengine-staging`. When deploying an
84+
[Uber JAR][uber-jar], the JAR is automatically copied into this staging
85+
directory and uploaded. It's possible to copy other files into this staging
86+
directory (such as additional JVM Agents) and having them available in the
87+
deployed App Engine runtime directory.
88+
89+
- To stage the files to be uploaded:
90+
```
91+
mvn appengine:stage
92+
```
93+
94+
[uber-jar]: https://stackoverflow.com/questions/11947037/what-is-an-uber-jar

‎appengine-java11/appengine-simple-jetty-main/README.md

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
# Embedded Jetty Server for Google App Engine Standard with Java 11
2+
3+
To migrate to the Java 11 runtime, your application must have a
4+
`Main` class that starts a web server. This sample is a shared artifact that
5+
provides a `Main` class to instantiate an HTTP server to run an embedded web
6+
application `WAR` file.
7+
8+
For more information on the Java 11 runtime, see
9+
[Migrating your App Engine app from Java 8 to Java 11](https://cloud.google.com/appengine/docs/standard/java11/java-differences).
10+
11+
## Install the dependency
12+
This sample is used as a dependency and must be install locally:
13+
```
14+
mvn install
15+
```
16+
17+
## Using the dependency
18+
See [`helloworld-servlet`](../helloworld-servlet) to see a complete example.
19+
20+
Your project's `pom.xml` needs to be updated accordingly:
21+
22+
- Add the `appengine-simple-jetty-main` dependency:
23+
```
24+
<dependency>
25+
<groupId>com.example.appengine.demo</groupId>
26+
<artifactId>simple-jetty-main</artifactId>
27+
<version>1</version>
28+
<scope>provided</scope>
29+
</dependency>
30+
```
31+
32+
- On deployment, the App Engine runtime uploads files located in
33+
`${build.directory}/appengine-staging`. Add the `maven-dependency-plugin` to
34+
the build in order to copy dependencies to the correct folder:
35+
```
36+
<plugin>
37+
<groupId>org.apache.maven.plugins</groupId>
38+
<artifactId>maven-dependency-plugin</artifactId>
39+
<version>3.1.1</version>
40+
<executions>
41+
<execution>
42+
<id>copy</id>
43+
<phase>prepare-package</phase>
44+
<goals>
45+
<goal>copy-dependencies</goal>
46+
</goals>
47+
<configuration>
48+
<outputDirectory>
49+
${project.build.directory}/appengine-staging
50+
</outputDirectory>
51+
</configuration>
52+
</execution>
53+
</executions>
54+
</plugin>
55+
```
56+
57+
To use the dependency add the entrypoint to your `app.yaml` file. The
58+
entrypoint field will start the Jetty server and load your `WAR` file.
59+
```
60+
runtime: java11
61+
instance_class: F2
62+
entrypoint: 'java -cp * com.example.appengine.demo.jettymain.Main helloworld.war'
63+
```
64+
65+
## Running locally
66+
The [Exec Maven Plugin][exec-plugin] has been added so you can run your
67+
application locally. It is possible to use the [Jetty Maven Plugin][jetty-plugin]
68+
for rapid development and testing, but using the Exec Maven Plugin will ensure
69+
the provided server is running your application as expected.
70+
71+
- Start the server with your `WAR` file as an argument:
72+
```
73+
mvn exec:java -Dexec.args="../sample/target/sample.war"
74+
```
75+
76+
[jetty-plugin]: https://www.eclipse.org/jetty/documentation/9.4.x/jetty-maven-plugin.html

‎appengine-java11/appengine-simple-jetty-main/pom.xml

Lines changed: 28 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -23,34 +23,57 @@
2323
<maven.compiler.target>11</maven.compiler.target>
2424
</properties>
2525

26+
<!-- [START gae_java11_server_dependencies] -->
2627
<dependencies>
28+
<!-- Embedded Jetty dependencies -->
2729
<dependency>
2830
<groupId>org.eclipse.jetty</groupId>
2931
<artifactId>jetty-server</artifactId>
30-
<version>9.4.14.v20181114</version>
32+
<version>9.4.18.v20190429</version>
3133
</dependency>
3234
<dependency>
3335
<groupId>org.eclipse.jetty</groupId>
3436
<artifactId>jetty-webapp</artifactId>
35-
<version>9.4.14.v20181114</version>
37+
<version>9.4.18.v20190429</version>
3638
<type>jar</type>
3739
</dependency>
3840
<dependency>
3941
<groupId>org.eclipse.jetty</groupId>
4042
<artifactId>jetty-util</artifactId>
41-
<version>9.4.14.v20181114</version>
43+
<version>9.4.18.v20190429</version>
4244
</dependency>
4345
<dependency>
4446
<groupId>org.eclipse.jetty</groupId>
4547
<artifactId>jetty-annotations</artifactId>
46-
<version>9.4.14.v20181114</version>
48+
<version>9.4.18.v20190429</version>
4749
<type>jar</type>
4850
</dependency>
4951
<!-- extra explicit dependency needed because there is a JSP in the sample-->
5052
<dependency>
5153
<groupId>org.eclipse.jetty</groupId>
5254
<artifactId>apache-jsp</artifactId>
53-
<version>9.4.14.v20181114</version>
55+
<version>9.4.18.v20190429</version>
5456
</dependency>
5557
</dependencies>
58+
<!-- [END gae_java11_server_dependencies] -->
59+
60+
<build>
61+
<plugins>
62+
<!-- Exec Maven Plugin provides goals to help execute Main class locally -->
63+
<!-- [START gae_java11_exec_plugin] -->
64+
<plugin>
65+
<groupId>org.codehaus.mojo</groupId>
66+
<artifactId>exec-maven-plugin</artifactId>
67+
<version>1.6.0</version>
68+
<executions>
69+
<execution><goals><goal>java</goal></goals></execution>
70+
</executions>
71+
<configuration>
72+
<mainClass>com.example.appengine.demo.jettymain.Main</mainClass>
73+
</configuration>
74+
</plugin>
75+
<!-- [END gae_java11_exec_plugin] -->
76+
77+
</plugins>
78+
</build>
5679
</project>

‎appengine-java11/appengine-simple-jetty-main/src/main/java/com/example/appengine/demo/jettymain/Main.java

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@
1616

1717
package com.example.appengine.demo.jettymain;
1818

19+
// [START gae_java11_server]
1920
import org.eclipse.jetty.server.Server;
2021
import org.eclipse.jetty.webapp.Configuration.ClassList;
2122
import org.eclipse.jetty.webapp.WebAppContext;
@@ -61,3 +62,4 @@ public static void main(String[] args) throws Exception {
6162
server.join();
6263
}
6364
}
65+
// [END gae_java11_server]

0 commit comments

Comments
 (0)