Customize a node docs enhancement

website_and_docs/content/documentation/grid/advanced_features/customize_node.en.md

@@ -2,14 +2,10 @@
 title: "Customizing a Node"
 linkTitle: "Customize Node"
 weight: 4
-aliases: [
-"/documentation/en/grid/grid_4/customize_node/",
-"/documentation/grid/advanced_features/customize_node/"
-]
 ---
 
 
-### How to customize a Node
+## How to customize a Node
 
 There are times when we would like a Node to be customized to our needs. 
 
@@ -29,20 +25,37 @@ Following steps can be followed for this:
 
 Let's see an example of all this:
 
+### Custom Node as an uber jar
+
 1. Create a sample project using your favourite build tool (**Maven**|**Gradle**).
-2. Add the below two dependencies to your sample project.
-  * [org.seleniumhq.selenium/selenium-java](https://mvnrepository.com/artifact/org.seleniumhq.selenium/selenium-java)
-  * [org.seleniumhq.selenium/selenium-grid](https://mvnrepository.com/artifact/org.seleniumhq.selenium/selenium-grid)
+2. Add the below dependency to your sample project.
+    * [org.seleniumhq.selenium/selenium-grid](https://mvnrepository.com/artifact/org.seleniumhq.selenium/selenium-grid)
 3. Add your customized Node to the project.
-4. Build an [uber jar](https://imagej.net/develop/uber-jars) if you would like to just use `java -jar` to start the Node.
+4. Build an [uber jar](https://imagej.net/develop/uber-jars) to be able to start the Node using `java -jar` command.
 5. Now start the Node using the command:
 
 ```bash
-java -jar custom_node-1.0-SNAPSHOT.jar node \
---node-implementation org.seleniumhq.samples.CommentatingNode
+java -jar custom_node-server.jar node \
+--node-implementation org.seleniumhq.samples.DecoratedLoggingNode
 ```
 
-Here's a sample that just prints some messages on to the console whenever there's an activity of interest (session created, session deleted, a webdriver command executed etc.,) on the Node.
+**Note:** If you are using Maven as a build tool, please prefer using [maven-shade-plugin](https://maven.apache.org/plugins/maven-shade-plugin) instead of [maven-assembly-plugin](https://maven.apache.org/plugins/maven-assembly-plugin) because maven-assembly plugin seems to have issues with being able to merge multiple Service Provider Interface files (`META-INF/services`)
+
+### Custom Node as a regular jar
+
+1. Create a sample project using your favourite build tool (**Maven**|**Gradle**).
+2. Add the below dependency to your sample project.
+    * [org.seleniumhq.selenium/selenium-grid](https://mvnrepository.com/artifact/org.seleniumhq.selenium/selenium-grid)
+3. Add your customized Node to the project.
+4. Build a jar of your project using your build tool.
+5. Now start the Node using the command:
+
+```bash
+java -jar selenium-server-4.6.0.jar \
+--ext custom_node-1.0-SNAPSHOT.jar node \
+--node-implementation org.seleniumhq.samples.DecoratedLoggingNode
+```
+Below is a sample that just prints some messages on to the console whenever there's an activity of interest (session created, session deleted, a webdriver command executed etc.,) on the Node.
 
 
 <details>
@@ -88,7 +101,10 @@ public class DecoratedLoggingNode extends Node {
     BaseServerOptions serverOptions = new BaseServerOptions(config);
     URI uri = serverOptions.getExternalUri();
     SecretOptions secretOptions = new SecretOptions(config);
+
+    // Refer to the foot notes for additional context on this line.
     Node node = LocalNodeFactory.create(config);
+
     DecoratedLoggingNode wrapper = new DecoratedLoggingNode(loggingOptions.getTracer(),
         uri, secretOptions.getRegistrationSecret());
     wrapper.node = node;
@@ -208,4 +224,23 @@ public class DecoratedLoggingNode extends Node {
   }
 }
 ```
-</details>
+</details>
+
+**_Foot Notes:_**
+
+In the above example, the line `Node node = LocalNodeFactory.create(config);` explicitly creates a `LocalNode`.
+
+There are basically 2 types of *user facing implementations* of `org.openqa.selenium.grid.node.Node` available. 
+
+These classes are good starting points to learn how to build a custom Node and also to learn the internals of a Node.
+
+* `org.openqa.selenium.grid.node.local.LocalNode` - Used to represent a long running Node and is the default implementation that gets wired in when you start a `node`. 
+    * It can be created by calling `LocalNodeFactory.create(config);`, where:
+      * `LocalNodeFactory` belongs to `org.openqa.selenium.grid.node.local`
+      * `Config` belongs to `org.openqa.selenium.grid.config`
+* `org.openqa.selenium.grid.node.k8s.OneShotNode` - This is a special reference implementation wherein the Node gracefully shuts itself down after servicing one test session. This class is currently not available as part of any pre-built maven artifact.
+  *  You can refer to the source code [here](https://github.com/SeleniumHQ/selenium/blob/trunk/java/src/org/openqa/selenium/grid/node/k8s/OneShotNode.java) to understand its internals. 
+  *  To build it locally refer [here](https://github.com/SeleniumHQ/selenium/blob/trunk/deploys/k8s/README.md). 
+  *  It can be created by calling `OneShotNode.create(config)`, where:
+      * `OneShotNode` belongs to `org.openqa.selenium.grid.node.k8s`
+      * `Config` belongs to `org.openqa.selenium.grid.config`

website_and_docs/content/documentation/grid/advanced_features/customize_node.ja.md

@@ -2,10 +2,6 @@
 title: "Customizing a Node"
 linkTitle: "Customize Node"
 weight: 4
-aliases: [
-"/documentation/en/grid/grid_4/customize_node/",
-"/documentation/grid/advanced_features/customize_node/"
-]
 ---
 
 {{% pageinfo color="warning" %}}
@@ -17,7 +13,7 @@ aliases: [
 </p>
 {{% /pageinfo %}}
 
-### How to customize a Node
+## How to customize a Node
 
 There are times when we would like a Node to be customized to our needs. 
 
@@ -37,20 +33,37 @@ Following steps can be followed for this:
 
 Let's see an example of all this:
 
+### Custom Node as an uber jar
+
 1. Create a sample project using your favourite build tool (**Maven**|**Gradle**).
-2. Add the below two dependencies to your sample project.
-  * [org.seleniumhq.selenium/selenium-java](https://mvnrepository.com/artifact/org.seleniumhq.selenium/selenium-java)
-  * [org.seleniumhq.selenium/selenium-grid](https://mvnrepository.com/artifact/org.seleniumhq.selenium/selenium-grid)
+2. Add the below dependency to your sample project.
+    * [org.seleniumhq.selenium/selenium-grid](https://mvnrepository.com/artifact/org.seleniumhq.selenium/selenium-grid)
 3. Add your customized Node to the project.
-4. Build an [uber jar](https://imagej.net/develop/uber-jars) if you would like to just use `java -jar` to start the Node.
+4. Build an [uber jar](https://imagej.net/develop/uber-jars) to be able to start the Node using `java -jar` command.
 5. Now start the Node using the command:
 
 ```bash
-java -jar custom_node-1.0-SNAPSHOT.jar node \
---node-implementation org.seleniumhq.samples.CommentatingNode
+java -jar custom_node-server.jar node \
+--node-implementation org.seleniumhq.samples.DecoratedLoggingNode
 ```
 
-Here's a sample that just prints some messages on to the console whenever there's an activity of interest (session created, session deleted, a webdriver command executed etc.,) on the Node.
+**Note:** If you are using Maven as a build tool, please prefer using [maven-shade-plugin](https://maven.apache.org/plugins/maven-shade-plugin) instead of [maven-assembly-plugin](https://maven.apache.org/plugins/maven-assembly-plugin) because maven-assembly plugin seems to have issues with being able to merge multiple Service Provider Interface files (`META-INF/services`)
+
+### Custom Node as a regular jar
+
+1. Create a sample project using your favourite build tool (**Maven**|**Gradle**).
+2. Add the below dependency to your sample project.
+    * [org.seleniumhq.selenium/selenium-grid](https://mvnrepository.com/artifact/org.seleniumhq.selenium/selenium-grid)
+3. Add your customized Node to the project.
+4. Build a jar of your project using your build tool.
+5. Now start the Node using the command:
+
+```bash
+java -jar selenium-server-4.6.0.jar \
+--ext custom_node-1.0-SNAPSHOT.jar node \
+--node-implementation org.seleniumhq.samples.DecoratedLoggingNode
+```
+Below is a sample that just prints some messages on to the console whenever there's an activity of interest (session created, session deleted, a webdriver command executed etc.,) on the Node.
 
 
 <details>
@@ -96,7 +109,10 @@ public class DecoratedLoggingNode extends Node {
     BaseServerOptions serverOptions = new BaseServerOptions(config);
     URI uri = serverOptions.getExternalUri();
     SecretOptions secretOptions = new SecretOptions(config);
+
+    // Refer to the foot notes for additional context on this line.
     Node node = LocalNodeFactory.create(config);
+
     DecoratedLoggingNode wrapper = new DecoratedLoggingNode(loggingOptions.getTracer(),
         uri, secretOptions.getRegistrationSecret());
     wrapper.node = node;
@@ -216,4 +232,23 @@ public class DecoratedLoggingNode extends Node {
   }
 }
 ```
-</details>
+</details>
+
+**_Foot Notes:_**
+
+In the above example, the line `Node node = LocalNodeFactory.create(config);` explicitly creates a `LocalNode`.
+
+There are basically 2 types of *user facing implementations* of `org.openqa.selenium.grid.node.Node` available. 
+
+These classes are good starting points to learn how to build a custom Node and also to learn the internals of a Node.
+
+* `org.openqa.selenium.grid.node.local.LocalNode` - Used to represent a long running Node and is the default implementation that gets wired in when you start a `node`. 
+    * It can be created by calling `LocalNodeFactory.create(config);`, where:
+      * `LocalNodeFactory` belongs to `org.openqa.selenium.grid.node.local`
+      * `Config` belongs to `org.openqa.selenium.grid.config`
+* `org.openqa.selenium.grid.node.k8s.OneShotNode` - This is a special reference implementation wherein the Node gracefully shuts itself down after servicing one test session. This class is currently not available as part of any pre-built maven artifact.
+  *  You can refer to the source code [here](https://github.com/SeleniumHQ/selenium/blob/trunk/java/src/org/openqa/selenium/grid/node/k8s/OneShotNode.java) to understand its internals. 
+  *  To build it locally refer [here](https://github.com/SeleniumHQ/selenium/blob/trunk/deploys/k8s/README.md). 
+  *  It can be created by calling `OneShotNode.create(config)`, where:
+      * `OneShotNode` belongs to `org.openqa.selenium.grid.node.k8s`
+      * `Config` belongs to `org.openqa.selenium.grid.config`

website_and_docs/content/documentation/grid/advanced_features/customize_node.pt-br.md

@@ -2,10 +2,6 @@
 title: "Customizing a Node"
 linkTitle: "Customize Node"
 weight: 4
-aliases: [
-"/documentation/en/grid/grid_4/customize_node/",
-"/documentation/grid/advanced_features/customize_node/"
-]
 ---
 
 {{% pageinfo color="warning" %}}
@@ -17,7 +13,7 @@ aliases: [
 </p>
 {{% /pageinfo %}}
 
-### How to customize a Node
+## How to customize a Node
 
 There are times when we would like a Node to be customized to our needs. 
 
@@ -37,23 +33,41 @@ Following steps can be followed for this:
 
 Let's see an example of all this:
 
+### Custom Node as an uber jar
+
 1. Create a sample project using your favourite build tool (**Maven**|**Gradle**).
-2. Add the below two dependencies to your sample project.
-  * [org.seleniumhq.selenium/selenium-java](https://mvnrepository.com/artifact/org.seleniumhq.selenium/selenium-java)
-  * [org.seleniumhq.selenium/selenium-grid](https://mvnrepository.com/artifact/org.seleniumhq.selenium/selenium-grid)
+2. Add the below dependency to your sample project.
+    * [org.seleniumhq.selenium/selenium-grid](https://mvnrepository.com/artifact/org.seleniumhq.selenium/selenium-grid)
 3. Add your customized Node to the project.
-4. Build an [uber jar](https://imagej.net/develop/uber-jars) if you would like to just use `java -jar` to start the Node.
+4. Build an [uber jar](https://imagej.net/develop/uber-jars) to be able to start the Node using `java -jar` command.
 5. Now start the Node using the command:
 
 ```bash
-java -jar custom_node-1.0-SNAPSHOT.jar node \
---node-implementation org.seleniumhq.samples.CommentatingNode
+java -jar custom_node-server.jar node \
+--node-implementation org.seleniumhq.samples.DecoratedLoggingNode
 ```
 
-Here's a sample that just prints some messages on to the console whenever there's an activity of interest (session created, session deleted, a webdriver command executed etc.,) on the Node.
+**Note:** If you are using Maven as a build tool, please prefer using [maven-shade-plugin](https://maven.apache.org/plugins/maven-shade-plugin) instead of [maven-assembly-plugin](https://maven.apache.org/plugins/maven-assembly-plugin) because maven-assembly plugin seems to have issues with being able to merge multiple Service Provider Interface files (`META-INF/services`)
+
+### Custom Node as a regular jar
+
+1. Create a sample project using your favourite build tool (**Maven**|**Gradle**).
+2. Add the below dependency to your sample project.
+    * [org.seleniumhq.selenium/selenium-grid](https://mvnrepository.com/artifact/org.seleniumhq.selenium/selenium-grid)
+3. Add your customized Node to the project.
+4. Build a jar of your project using your build tool.
+5. Now start the Node using the command:
+
+```bash
+java -jar selenium-server-4.6.0.jar \
+--ext custom_node-1.0-SNAPSHOT.jar node \
+--node-implementation org.seleniumhq.samples.DecoratedLoggingNode
+```
+Below is a sample that just prints some messages on to the console whenever there's an activity of interest (session created, session deleted, a webdriver command executed etc.,) on the Node.
+
 
-<summary>Sample customized node</summary>
 <details>
+<summary>Sample customized node</summary>
 
 ```java
 package org.seleniumhq.samples;
@@ -95,7 +109,10 @@ public class DecoratedLoggingNode extends Node {
     BaseServerOptions serverOptions = new BaseServerOptions(config);
     URI uri = serverOptions.getExternalUri();
     SecretOptions secretOptions = new SecretOptions(config);
+
+    // Refer to the foot notes for additional context on this line.
     Node node = LocalNodeFactory.create(config);
+
     DecoratedLoggingNode wrapper = new DecoratedLoggingNode(loggingOptions.getTracer(),
         uri, secretOptions.getRegistrationSecret());
     wrapper.node = node;
@@ -215,4 +232,23 @@ public class DecoratedLoggingNode extends Node {
   }
 }
 ```
-</details>
+</details>
+
+**_Foot Notes:_**
+
+In the above example, the line `Node node = LocalNodeFactory.create(config);` explicitly creates a `LocalNode`.
+
+There are basically 2 types of *user facing implementations* of `org.openqa.selenium.grid.node.Node` available. 
+
+These classes are good starting points to learn how to build a custom Node and also to learn the internals of a Node.
+
+* `org.openqa.selenium.grid.node.local.LocalNode` - Used to represent a long running Node and is the default implementation that gets wired in when you start a `node`. 
+    * It can be created by calling `LocalNodeFactory.create(config);`, where:
+      * `LocalNodeFactory` belongs to `org.openqa.selenium.grid.node.local`
+      * `Config` belongs to `org.openqa.selenium.grid.config`
+* `org.openqa.selenium.grid.node.k8s.OneShotNode` - This is a special reference implementation wherein the Node gracefully shuts itself down after servicing one test session. This class is currently not available as part of any pre-built maven artifact.
+  *  You can refer to the source code [here](https://github.com/SeleniumHQ/selenium/blob/trunk/java/src/org/openqa/selenium/grid/node/k8s/OneShotNode.java) to understand its internals. 
+  *  To build it locally refer [here](https://github.com/SeleniumHQ/selenium/blob/trunk/deploys/k8s/README.md). 
+  *  It can be created by calling `OneShotNode.create(config)`, where:
+      * `OneShotNode` belongs to `org.openqa.selenium.grid.node.k8s`
+      * `Config` belongs to `org.openqa.selenium.grid.config`