diff --git a/docs.old/src/quick-start.md b/docs.old/src/quick-start.md index 4792c35..74c7927 100644 --- a/docs.old/src/quick-start.md +++ b/docs.old/src/quick-start.md @@ -79,7 +79,7 @@ public interface ConfigSource { - `AbstractConfigSourceHandlerContext` - `DefaultConfigSourceHandlerContext` -## 2. implementing your handler for pipeline +## Implementing your handler for pipeline we can implement `MapConfigSourceHandler` and `SystemConfigSourceHandler` (they are all in the [ConfigSource handler example](https://github.com/foldright/auto-pipeline/blob/main/auto-pipeline-examples/src/main/java/com/foldright/examples/config/handler)): @@ -144,4 +144,5 @@ pipeline.get("java.specification.version") // from system properties / SystemConfigSourceHandler ``` -check the runnable [test case](https://github.com/foldright/auto-pipeline/blob/main/auto-pipeline-examples/src/test/java/com/foldright/examples/config/pipeline/ConfigSourceTest.kt) for details. +## What's next: + diff --git a/docs/docs/tutorial-basics/01-add-dependency.md b/docs/docs/tutorial-basics/01-add-dependency.md deleted file mode 100644 index 74e4c4f..0000000 --- a/docs/docs/tutorial-basics/01-add-dependency.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -sidebar_position: 1 ---- - -# Add dependency - -`auto-pipeline` has published to maven central, click here -to [find the latest version](https://search.maven.org/search?q=g:com.foldright.auto-pipeline). current the latest version is `0.3.0` - - - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; - - - - ```xml title="pom.xml" - - com.foldright.auto-pipeline - auto-pipeline-processor - 0.3.0 - provided - - ``` - - - ```kotlin title="build.gradle.kts" - // the auto-pipeline annotation will be used in your interface type - compileOnly("com.foldright.auto-pipeline:auto-pipeline-annotations:0.3.0") - // the auto-pipeline annotation processor will generate the pipeline classes for the interface. - // use "annotationProcessor" scope because it's only needed at annotation processing time. - annotationProcessor("com.foldright.auto-pipeline:auto-pipeline-processor:0.3.0") - ``` - - - ```groovy title="build.gradle" - compileOnly 'com.foldright.auto-pipeline:auto-pipeline-annotations:0.3.0' - annotationProcessor 'com.foldright.auto-pipeline:auto-pipeline-processor:0.3.0' - ``` - - - -:::info[note the dependency scope!] -The auto-pipeline annotation processor will generate the pipeline classes for the interface. - -Annotation processor dependency should be "provided" scope, because it's only needed at compile time. -::: diff --git a/docs/docs/tutorial-basics/01-quick-start.md b/docs/docs/tutorial-basics/01-quick-start.md new file mode 100644 index 0000000..37b375f --- /dev/null +++ b/docs/docs/tutorial-basics/01-quick-start.md @@ -0,0 +1,177 @@ +--- +sidebar_position: 1 +--- +# Quick start + +It's very easy to use `Auto-Pipeline`, just follow the steps. + +## Step1. add dependency + +`auto-pipeline` has published to maven central, click here +to [find the latest version](https://search.maven.org/search?q=g:com.foldright.auto-pipeline). current the latest version is `0.3.0` + + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + + + + ```xml title="pom.xml" + + com.foldright.auto-pipeline + auto-pipeline-processor + 0.3.0 + provided + + ``` + + + ```kotlin title="build.gradle.kts" + // the auto-pipeline annotation will be used in your interface type + compileOnly("com.foldright.auto-pipeline:auto-pipeline-annotations:0.3.0") + // the auto-pipeline annotation processor will generate the pipeline classes for the interface. + // use "annotationProcessor" scope because it's only needed at annotation processing time. + annotationProcessor("com.foldright.auto-pipeline:auto-pipeline-processor:0.3.0") + ``` + + + ```groovy title="build.gradle" + compileOnly 'com.foldright.auto-pipeline:auto-pipeline-annotations:0.3.0' + annotationProcessor 'com.foldright.auto-pipeline:auto-pipeline-processor:0.3.0' + ``` + + + +:::info[note the dependency scope!] +The auto-pipeline annotation processor will generate the pipeline classes for the interface. + +Annotation processor dependency should be "provided" scope, because it's only needed at compile time. +::: + +## Step2. Using `@AutoPipeline` + +Very simple and easy. + +### Define Your interface +Let's define your business interface called `ConfigSource`. + +The `ConfigSource` has the `get()` method, input a string as key and output a string as the value. +like this: + +```java title="ConfigSource.java" +public interface ConfigSource { + String get(String key); +} +``` + +### Annotation the interface + +If we want `ConfigSource` has some extensibility, we can apply the `chain of responsibility` pattern to it for extensibility. + +We can simply add `@AutoPipelin` to `ConfigSource` to make `ConfigSource` more extensible： + +```java title="ConfigSource.java" +@AutoPipeline // add @AutoPipeline here! +public interface ConfigSource { + String get(String key); +} +``` + +And then we compile our code, `auto-pipeline-processor` will auto generate pipeline java files for `ConfigSource` into subpackage `pipeline`: + +- `ConfigSourceHandler.java` the responsibility interface we want to implement for extensibility +- `ConfigSourcePipeline.java` the chain +- `ConfigSourceHandlerContext.java` +- `AbstractConfigSourceHandlerContext.java` +- `DefaultConfigSourceHandlerContext.java` + +Oh yeah! We add `@AutoPipeline` and we get 5 files for free. The 5 files make up our ConfigSource pipeline! + +## Step3. write your business code + +After generating java files, we can now add our business code to the implements. + +we can implement `MapConfigSourceHandler` and `SystemConfigSourceHandler` (they are all in the [ConfigSource handler example](https://github.com/foldright/auto-pipeline/blob/main/auto-pipeline-examples/src/main/java/com/foldright/examples/config/handler)): + +```java title="MapConfigSourceHandler.java" +public class MapConfigSourceHandler implements ConfigSourceHandler { + private final Map map; + + public MapConfigSourceHandler(Map map) { + this.map = map; + } + + @Override + public String get(String key, ConfigSourceHandlerContext context) { + String value = map.get(key); + if (StringUtils.isNotBlank(value)) { + return value; + } + return context.get(key); + } +} +``` +```java title="SystemConfigSourceHandler.java" +public class SystemConfigSourceHandler implements ConfigSourceHandler { + public static final SystemConfigSourceHandler INSTANCE = new SystemConfigSourceHandler(); + + @Override + public String get(String key, ConfigSourceHandlerContext context) { + String value = System.getProperty(key); + if (StringUtils.isNotBlank(value)) { + return value; + } + return context.get(key); + } +} +``` + +## Step4. using your pipeline + +Now you can create the `ConfigSourcePipeline` by composing `ConfigSourceHandler`s. + +And using the pipeline as the `ConfigSource`: + +```java title="Main.java" +public class Main { + public static void main(String[] args) { + Map mapConfig = new HashMap(); + mapConfig.put("hello", "world"); + ConfigSourceHandler mapConfigSourceHandler = new MapConfigSourceHandler(mapConfig); + + ConfigSource pipeline = new ConfigSourcePipeline() + .addLast(mapConfigSourceHandler) + .addLast(SystemConfigSourceHandler.INSTANCE); + } +} +``` + +:::info[the ConfigSourcePipeline!] +In fact, the `ConfigSourcePipeline.java` implements ConfigSource. + +So we can use `ConfigSourcePipeline` as `ConfigSource`. +::: + +Now, we can use the `pipeline.get(...)` to invoke the chain! 🎉 + +```java title="Main.java" +public class Main { + public static void main(String[] args) { + // ... + + pipeline.get("hello"); + // get value "world" + // from mapConfig / mapConfigSourceHandler + + pipeline.get("java.specification.version"); + // get value "1.8" + // from system properties / SystemConfigSourceHandler + } +} +``` + +That's all, the `@AutoPipeline` help you generate the Pipeline Design Pattern Code! It's never been easier! + + +## What's next? +- check the runnable [test case](https://github.com/foldright/auto-pipeline/blob/main/auto-pipeline-examples/src/test/java/com/foldright/examples/config/pipeline/ConfigSourceTest.kt) for details.