Skip to content

Commit

Permalink
change documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@monxxi
monxxi committed Jun 15, 2020
1 parent 80d1ea1 commit 020e628
Show file tree
Hide file tree
Showing 2 changed files with 43 additions and 148 deletions.
113 changes: 36 additions & 77 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -108,100 +108,59 @@ The different [use cases](USE_CASES.md) are listed on another page.

## Prompt options tree

Choose your own adventure module!
Do your own configuration step-by-step!

The **END** represents the end of the prompts below, when files are written after confirmation (you can use the `--force` option with `yo jhipster-kafka` to overwrite all files).

<ul>
<li>Big Bang Mode (build a configuration from scratch) <strong>(default)</strong>
<li>Do you want to clean up your current Kafka configuration?
<ul>
<li>Which components would you like to generate?
<ul>
<li>Consumer</li>
<li>Producer</li>
</ul>
</li>
<li>For which entity (class name)?
<ul>
<li>No entity (will be typed String) <strong>(default)</strong>
<ul>
<li>How would you prefix your objects (no entity, for instance: [SomeEventType]Consumer|Producer...)?</li>
</ul>
</li>
<li>Foo</li>
<li>Bar</li>
<li>...</li>
</ul>
</li>
<li><em>If "Consumer" was selected:</em> What is the consumer polling timeout (in ms)? <strong>(default = 10000)</strong></li>
<li><em>If "Consumer" was selected:</em> Define the auto offset reset policy (what to do when there is no initial offset in Kafka or if the current offset does not exist any more on the server)?
<ul>
<li>earliest (automatically reset the offset to the earliest offset) <strong>(default)</strong></li>
<li>latest (automatically reset the offset to the latest offset)</li>
<li>none (throw exception to the consumer if no previous offset is found for the consumer group)</li>
</ul>
</li>
<li>For which topic?
<ul>
<li>Default topic name following this convention: message_type.application_type.entity_name <strong>(default)</strong></li>
<li>Custom topic name
<ul>
<li>What is the topic name?</li>
</ul>
</li>
<li>queuing.application_name.existing_topic_name</li>
<li>...</li>
</ul>
</li>
<li>Do you want to continue to the next entity/prefix or exit? <strong>(default = Y)</strong></li>
<li><strong>END</strong></li>
<li><em>If "y" was selected:</em> all configurations and classes will be deleted and fully regenerated</li>
<li><em>If "n" was selected <b>(default)</b>:</em> the new configuration will be merged with the previous one</li>
</ul>
</li>
<li>Incremental Mode (upgrade an existing configuration)
<li>For which entity (class name)?
<ul>
<li>For which entity (class name)?
<ul>
<li>No entity (will be typed String) <strong>(default)</strong>
<ul>
<li>How would you prefix your objects (no entity, for instance: [SomeEventType]Consumer|Producer...)?</li>
</ul>
</li>
<li>Foo</li>
<li>Bar</li>
<li>...</li>
</ul>
</li>
<li>Which components would you like to generate?
<ul>
<li>Consumer</li>
<li>Producer</li>
</ul>
</li>
<li>For which topic?
<li>No entity (will be typed String) <strong>(default)</strong>
<ul>
<li>Default topic name following this convention: message_type.application_type.entity_name <strong>(default)</strong></li>
<li>Custom topic name
<ul>
<li>What is the topic name?</li>
</ul>
</li>
<li>queuing.application_name.existing_topic_name</li>
<li>...</li>
<li>How would you prefix your objects (no entity, for instance: [SomeEventType]Consumer|Producer...)?</li>
</ul>
</li>
<li><em>If "Consumer" was selected:</em> What is the consumer polling timeout (in ms)? <strong>(default = 10000)</strong></li>
<li><em>If "Consumer" was selected:</em> Define the auto offset reset policy (what to do when there is no initial offset in Kafka or if the current offset does not exist any more on the server)?
<li>Foo</li>
<li>Bar</li>
<li>...</li>
</ul>
</li>
<li>Which components would you like to generate?
<ul>
<li>Consumer</li>
<li>Producer</li>
</ul>
</li>
<li>For which topic?
<ul>
<li>Default topic name following this convention: message_type.application_type.entity_name <strong>(default)</strong></li>
<li>Custom topic name
<ul>
<li>earliest (automatically reset the offset to the earliest offset) <strong>(default)</strong></li>
<li>latest (automatically reset the offset to the latest offset)</li>
<li>none (throw exception to the consumer if no previous offset is found for the consumer group)</li>
<li>What is the topic name?</li>
</ul>
</li>
<li>Do you want to continue adding consumers or producers? <strong>(default = N)</strong></li>
<li><em>If "N" was selected:</em> <strong>END</strong></li>
<li>queuing.application_name.existing_topic_name</li>
<li>...</li>
</ul>
</li>
<li><em>If "Consumer" was selected:</em> What is the consumer polling timeout (in ms)? <strong>(default = 10000)</strong></li>
<li><em>If "Consumer" was selected:</em> Define the auto offset reset policy (what to do when there is no initial offset in Kafka or if the current offset does not exist any more on the server)?
<ul>
<li>earliest (automatically reset the offset to the earliest offset) <strong>(default)</strong></li>
<li>latest (automatically reset the offset to the latest offset)</li>
<li>none (throw exception to the consumer if no previous offset is found for the consumer group)</li>
</ul>
</li>
<li>Do you want to continue adding consumers or producers? <strong>(default = N)</strong></li>
<li><em>If "N" was selected:</em> <strong>END</strong></li>
</ul>

</code>

## Skip prompts
Expand Down
78 changes: 7 additions & 71 deletions USE_CASES.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,37 +8,19 @@ The **topic naming convention** has been set to: `message_type.application_name.
- application_name: the application base name
- entity_name: the entity name (or the prefix if no entity) which is consumed

### Big Bang Mode
### Define your configuration Step-by-step

The Big Bang Mode allows the user to rewrite from scratch all the Kafka configuration (Java files and `application.yml`) to generate new components.
This modules allows the user to write new Kafka configuration (new Java files and `application.yml` updates). And in order to achieve it, prompt options are asked step-by-step until you decide to finish your configuration.

### Incremental Mode

The Incremental Mode allows the user to write new Kafka configuration (new Java files and `application.yml` updates) to generate new components over previous configuration. In this mode prompt options are asked and there is a loop for these questions.
You can choose to merge the new configuration with the previous configuration or just replace it, by selecting `"y"` or `"n"` to the question `"Do you want to clean up your current Kafka configuration?"`

### Create a consumer linked to an entity

After following the first 3 steps of the [basic usage](README.md#basic-usage) above, choose a mode and follow the steps:

#### Big Bang Mode

1. Create a new entity if not already generated with: `jhipster entity Foo`
2. In the same folder, run `yo jhipster-kafka`
3. "Which type of generation do you want?" - Big Bang Mode (build a configuration from scratch)
4. "Which components would you like to generate?" - Consumer
5. "For which entity (class name)?" - Foo (the available entities are retrieved in the `.jhipster` folder as `.json`)
6. "What is the consumer polling timeout (in ms)?" - Your answer or '10000' by default (global for all consumers)
7. "Define the auto offset reset policy?" - Your answer or 'earliest' by default (global for all consumers)
8. "Which topic for Foo?" - Any choice (choosing "Custom topic name" will add another question "What is the topic name for Foo?")
9. Loop on each entity with step 8
10. Overwrite all files in conflict
11. `FooConsumer` (consumes `Foo`) is available with a `FooDeserializer`

#### Incremental Mode

1. Create a new entity if not already generated with: `jhipster entity Foo`
2. In the same folder, run `yo jhipster-kafka`
3. "Which type of generation do you want?" - Incremental Mode (upgrade an existing configuration)
3. "Do you want to clean up your current Kafka configuration?" - `'y' or 'n'`
4. "For which entity (class name)?" - Foo (the available entities are retrieved in the `.jhipster` folder as `.json`)
5. "Which components would you like to generate?" - Consumer
6. "For which topic?" - Any choice (choosing "Custom topic name" will add another question "What is the topic name?")
Expand All @@ -52,23 +34,9 @@ After following the first 3 steps of the [basic usage](README.md#basic-usage) ab

After following the first 3 steps of the [basic usage](README.md#basic-usage) above, choose a mode and follow the steps:

#### Big Bang Mode

1. Create a new entity if not already generated with: `jhipster entity Foo`
2. In the same folder, run `yo jhipster-kafka`
3. "Which type of generation do you want?" - Big Bang Mode (build a configuration from scratch)
4. "Which components would you like to generate?" - Producer
5. "For which entity (class name)?" - Foo (the available entities are retrieved in the `.jhipster` folder as `.json`)
6. "Which topic for Foo?" - Any choice (choosing "Custom topic name" will add another question "What is the topic name for Foo?")
7. Loop on each entity with step 6
8. Overwrite all files in conflict
9. `FooProducer` (produces `Foo`) is available with a `FooSerializer` and a `FooKafkaResource` to [help testing](README.md#test-consumers-and-producers)

#### Incremental Mode

1. Create a new entity if not already generated with: `jhipster entity Foo`
2. In the same folder, run `yo jhipster-kafka`
3. "Which type of generation do you want?" - Incremental Mode (upgrade an existing configuration)
3. "Do you want to clean up your current Kafka configuration?" - `'y' or 'n'`
4. "For which entity (class name)?" - Foo (the available entities are retrieved in the `.jhipster` folder as `.json`)
5. "Which components would you like to generate?" - Producer
6. "For which topic?" - Any choice (choosing "Custom topic name" will add another question "What is the topic name?")
Expand All @@ -80,26 +48,9 @@ After following the first 3 steps of the [basic usage](README.md#basic-usage) ab

After following the first 3 steps of the [basic usage](README.md#basic-usage) above, choose a mode and follow the steps:

#### Big Bang Mode

1. Create a new entity if not already generated with: `jhipster entity Foo`
2. In the same folder, run `yo jhipster-kafka`
3. "Which type of generation do you want?" - Big Bang Mode (build a configuration from scratch)
4. "Which components would you like to generate?" - Consumer
5. "For which entity (class name)?" - No entity (will be typed String)
6. "How would you prefix your objects (no entity, for instance: [SomeEventType]Consumer|Producer...)?" - someEventType
7. "What is the consumer polling timeout (in ms)?" - Your answer or '10000' by default (global for all consumers)
8. "Define the auto offset reset policy?" - Your answer or 'earliest' by default (global for all consumers)
9. "Which topic for Foo?" - Any choice (choosing "Custom topic name" will add another question "What is the topic name for Foo?")
10. Loop on each entity with step 9
11. Overwrite all files in conflict
12. `SomeEventTypeConsumer` (consumes `String`) is available with a `SomeEventTypeDeserializer`

#### Incremental Mode

1. Create a new entity if not already generated with: `jhipster entity Foo`
2. In the same folder, run `yo jhipster-kafka`
3. "Which type of generation do you want?" - Incremental Mode (upgrade an existing configuration)
3. "Do you want to clean up your current Kafka configuration?" - `'y' or 'n'`
4. "For which entity (class name)?" - No entity (will be typed String)
5. "How would you prefix your objects (no entity, for instance: [SomeEventType]Consumer|Producer...)?" - someEventType
6. "Which components would you like to generate?" - Consumer
Expand All @@ -114,24 +65,9 @@ After following the first 3 steps of the [basic usage](README.md#basic-usage) ab

After following the first 3 steps of the [basic usage](README.md#basic-usage) above, choose a mode and follow the steps:

#### Big Bang Mode

1. Create a new entity if not already generated with: `jhipster entity Foo`
2. In the same folder, run `yo jhipster-kafka`
3. "Which type of generation do you want?" - Big Bang Mode (build a configuration from scratch)
4. "Which components would you like to generate?" - Producer
5. "For which entity (class name)?" - No entity (will be typed String)
6. "How would you prefix your objects (no entity, for instance: [SomeEventType]Consumer|Producer...)?" - someEventType
7. "Which topic for Foo?" - Any choice (choosing "Custom topic name" will add another question "What is the topic name for Foo?")
8. Loop on each entity with step 7
9. Overwrite all files in conflict
10. `SomeEventTypeProducer` (produces `String`) is available with a `SomeEventTypeSerializer` and a `SomeEventTypeKafkaResource` to [help testing](README.md#test-consumers-and-producers)

#### Incremental Mode

1. Create a new entity if not already generated with: `jhipster entity Foo`
2. In the same folder, run `yo jhipster-kafka`
3. "Which type of generation do you want?" - Incremental Mode (upgrade an existing configuration)
3. "Do you want to clean up your current Kafka configuration?" - `'y' or 'n'`
4. "For which entity (class name)?" - No entity (will be typed String)
5. "How would you prefix your objects (no entity, for instance: [SomeEventType]Consumer|Producer...)?" - someEventType
6. "Which components would you like to generate?" - Producer
Expand Down

0 comments on commit 020e628

Please sign in to comment.