pcoet commented on code in PR #22747: URL: https://github.com/apache/beam/pull/22747#discussion_r951944845
########## website/www/site/content/en/get-started/quickstart-java.md: ########## @@ -19,7 +19,7 @@ See the License for the specific language governing permissions and limitations under the License. --> -# Apache Beam Java SDK quickstart +# WordCount sample for Java Review Comment: Consider: "WordCount quickstart for Java" ########## website/www/site/content/en/get-started/quickstart/java.md: ########## @@ -0,0 +1,185 @@ +--- +title: "Beam Quickstart for Java" +aliases: + - /get-started/quickstart/ + - /use/quickstart/ + - /getting-started/ +--- +<!-- +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + +http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +--> + +# Apache Beam Java SDK quickstart + +This quickstart shows you how to run an +[example pipeline](https://github.com/apache/beam-starter-java) written with +the [Apache Beam Java SDK](/documentation/sdks/java), using the +[Direct Runner](/documentation/runners/direct/). The Direct Runner executes +pipelines locally on your machine. + +If you're interested in contributing to the Apache Beam Java codebase, see the +[Contribution Guide](/contribute). + +On this page: + +{{< toc >}} + +## Set up your development environment + +1. Download and install the + [Java Development Kit (JDK)](https://www.oracle.com/technetwork/java/javase/downloads/index.html) + version 8, 11, or 17. Verify that the + [JAVA_HOME](https://docs.oracle.com/javase/8/docs/technotes/guides/troubleshoot/envvars001.html) + environment variable is set and points to your JDK installation. +2. You can use either Gradle or Apache Maven to run this quickstart: + - Gradle: Install [Gradle](https://gradle.org/install/). + - Maven: Download [Apache Maven](https://maven.apache.org/download.cgi) and + follow the [installation guide](https://maven.apache.org/install.html) + for your operating system. + +## Clone the GitHub repository + +Clone or download the +[apache/beam-starter-java](https://github.com/apache/beam-starter-java) GitHub +repository and change into the beam-starter-java directory. + +{{< highlight >}} +git clone https://github.com/apache/beam-starter-java.git +cd beam-starter-java +{{< /highlight >}} + +## Run the quickstart + +**Gradle**: To run the quickstart with Gradle, run the following command: + +{{< highlight >}} +gradle run --args='--inputText=Greetings' +{{< /highlight >}} + +**Maven**: To run the quickstart with Maven, run the following command: + +{{< highlight >}} +mvn compile exec:java -Dexec.args=--inputText='Greetings' +{{< /highlight >}} + +The output is similar to the following: + +{{< highlight >}} +Hello +World! +Greetings +{{< /highlight >}} + +The lines might appear in a different order. + +## Explore the code + +The main code file for this quickstart is **App.java** +([GitHub](https://github.com/apache/beam-starter-java/blob/main/src/main/java/com/example/App.java)). +The code performs the following steps: + +1. Create a Beam pipeline. +3. Create an initial `PCollection`. +3. Apply a transform to the `PCollection`. +4. Run the pipeline, using the Direct Runner. + +### Create a pipeline + +The code first creates a `Pipeline` object. The `Pipeline` object builds up the +graph of transformations to be executed. + +{{< highlight >}} +var options = PipelineOptionsFactory.fromArgs(args).withValidation().as(Options.class); +var pipeline = Pipeline.create(options); +{{< /highlight >}} + +The `PipelineOptions` object lets you set various options for the pipeline. The +`fromArgs` method shown in this example parses command-line arguments, which +lets you set pipeline options through the command line. + +### Create an initial PCollection + +The `PCollection` abstraction represents a potentially distributed, +multi-element data set. A Beam pipeline needs a source of data to populate an +initial `PCollection`. The source can be bounded (with a known, fixed size) or +unbounded (with unlimited size). + +This example uses the +[`Create.of`](https://beam.apache.org/releases/javadoc/current/org/apache/beam/sdk/transforms/Create.html) +method to create a `PCollection` from an in-memory array of strings. The +resulting `PCollection` contains the strings "Hello", "World!", and a +user-provided input string. + +{{< highlight >}} +return pipeline + .apply("Create elements", Create.of(Arrays.asList("Hello", "World!", inputText))) Review Comment: Is this how @davidcavazos is spacing the example? I think in modern Java development we usually use 2 spaces for the first indent and 4 spaces for line wrapping: https://google.github.io/styleguide/javaguide.html#s4.2-block-indentation ########## website/www/site/content/en/get-started/quickstart/java.md: ########## @@ -0,0 +1,185 @@ +--- +title: "Beam Quickstart for Java" +aliases: Review Comment: See my comment above. I don't think we're quite ready to redirect this yet, especially given that the Dataflow getting started docs are still using the WordCount quickstarts. ########## website/www/site/content/en/get-started/quickstart-java.md: ########## @@ -1,5 +1,5 @@ --- -title: "Beam Quickstart for Java" +title: "WordCount sample for Java" aliases: Review Comment: We could also rename it "WordCount quickstart for Java" and not touch the filename. IMO, it's okay two have the old quickstarts and the new quickstarts live side-by-side for a while, especially because the Dataflow docs are still referring to the old WordCount quickstarts. We could just consider this a "soft" deprecation. ########## website/www/site/content/en/get-started/quickstart/java.md: ########## @@ -0,0 +1,185 @@ +--- +title: "Beam Quickstart for Java" +aliases: + - /get-started/quickstart/ + - /use/quickstart/ + - /getting-started/ +--- +<!-- +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + +http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +--> + +# Apache Beam Java SDK quickstart + +This quickstart shows you how to run an +[example pipeline](https://github.com/apache/beam-starter-java) written with +the [Apache Beam Java SDK](/documentation/sdks/java), using the +[Direct Runner](/documentation/runners/direct/). The Direct Runner executes +pipelines locally on your machine. + +If you're interested in contributing to the Apache Beam Java codebase, see the +[Contribution Guide](/contribute). + +On this page: + +{{< toc >}} + +## Set up your development environment + +1. Download and install the + [Java Development Kit (JDK)](https://www.oracle.com/technetwork/java/javase/downloads/index.html) + version 8, 11, or 17. Verify that the + [JAVA_HOME](https://docs.oracle.com/javase/8/docs/technotes/guides/troubleshoot/envvars001.html) + environment variable is set and points to your JDK installation. +2. You can use either Gradle or Apache Maven to run this quickstart: + - Gradle: Install [Gradle](https://gradle.org/install/). + - Maven: Download [Apache Maven](https://maven.apache.org/download.cgi) and + follow the [installation guide](https://maven.apache.org/install.html) + for your operating system. + +## Clone the GitHub repository + +Clone or download the +[apache/beam-starter-java](https://github.com/apache/beam-starter-java) GitHub +repository and change into the beam-starter-java directory. + +{{< highlight >}} +git clone https://github.com/apache/beam-starter-java.git +cd beam-starter-java +{{< /highlight >}} + +## Run the quickstart + +**Gradle**: To run the quickstart with Gradle, run the following command: + +{{< highlight >}} +gradle run --args='--inputText=Greetings' +{{< /highlight >}} + +**Maven**: To run the quickstart with Maven, run the following command: + +{{< highlight >}} +mvn compile exec:java -Dexec.args=--inputText='Greetings' +{{< /highlight >}} + +The output is similar to the following: + +{{< highlight >}} +Hello +World! +Greetings +{{< /highlight >}} + +The lines might appear in a different order. + +## Explore the code + +The main code file for this quickstart is **App.java** +([GitHub](https://github.com/apache/beam-starter-java/blob/main/src/main/java/com/example/App.java)). +The code performs the following steps: + +1. Create a Beam pipeline. +3. Create an initial `PCollection`. +3. Apply a transform to the `PCollection`. +4. Run the pipeline, using the Direct Runner. + +### Create a pipeline + +The code first creates a `Pipeline` object. The `Pipeline` object builds up the +graph of transformations to be executed. + +{{< highlight >}} +var options = PipelineOptionsFactory.fromArgs(args).withValidation().as(Options.class); +var pipeline = Pipeline.create(options); +{{< /highlight >}} + +The `PipelineOptions` object lets you set various options for the pipeline. The +`fromArgs` method shown in this example parses command-line arguments, which +lets you set pipeline options through the command line. + +### Create an initial PCollection + +The `PCollection` abstraction represents a potentially distributed, +multi-element data set. A Beam pipeline needs a source of data to populate an +initial `PCollection`. The source can be bounded (with a known, fixed size) or +unbounded (with unlimited size). + +This example uses the +[`Create.of`](https://beam.apache.org/releases/javadoc/current/org/apache/beam/sdk/transforms/Create.html) +method to create a `PCollection` from an in-memory array of strings. The +resulting `PCollection` contains the strings "Hello", "World!", and a +user-provided input string. + +{{< highlight >}} +return pipeline + .apply("Create elements", Create.of(Arrays.asList("Hello", "World!", inputText))) +{{< /highlight >}} + +### Apply a transform to the PCollection + +Transforms can change, filter, group, analyze, or otherwise process the +elements in a `PCollection`. This example uses the +[`MapElements`](https://beam.apache.org/releases/javadoc/current/org/apache/beam/sdk/transforms/MapElements.html) +transform, which maps the elements of a collection into a new collection: + +{{< highlight >}} +.apply("Print elements", + MapElements.into(TypeDescriptors.strings()).via(x -> { Review Comment: See question above about line wrapping and indents. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
