# Hello, World!

## Your First Program

The `xoom-helloworld` example is a pinned repository on our [GitHub VLINGO organization](https://github.com/vlingo/vlingo-helloworld). To use to it learn, first clone the repository and build the project. Open a console/command window so you can build the `xoom-helloworld` artifact and start it by executing the built `jar` file.

{% hint style="info" %}
Note that snapshot artifacts are hosted on GitHub, which requires credentials to be provided to Maven by way of it's `~/.m2/settings.xml`. This is [explained in more detail and with an example here](/getting-started.md).
{% endhint %}

```
$ git clone https://github.com/vlingo/xoom-helloworld.git
...
$ cd xoom-helloworld
$ mvn package
...
java -jar target/xoom-helloworld-withdeps.jar
...
$ 
```

The above `java` command executes the `jar` on the default port `18080`. If you would like to use a different port, you must provide it on the command line. This command uses port `8080`.

```
$ java -jar target/xoom-helloworld.jar 8080
```

The following examples assume that you have started the service with the default port, `18080`.

There are two resources, each with multiple endpoints. These are discussed next.

### Hello Resource

The first resource is used to get `"Hello, World!"` and similar messages.

You may `curl` with `GET` methods on the following resources.

```
$ curl -i -X GET http://localhost:18080/hello
```

The above `curl` responds with `200 OK` and the content body entity `"Hello, World!"`

You may also provide a path parameter to indicate to whom the service should say `"Hello"`. The second example responds with `200 OK` and the content body entity `"Hello, Me!"`

```
$ curl -i -X GET http://localhost:18080/hello/Me
```

In this Hello resource example there is only one component involved,[`io.vlingo.xoom.hello.infra.resource.HelloResource`](https://github.com/vlingo/xoom-helloworld/blob/master/src/main/java/io/vlingo/xoom/hello/infra/resource/HelloResource.java).

### Greeting Resource

The second resource is a bit more involved, and is used to maintain any number of `Greeting` messages. These greetings have the following data associated with them.

* `id`: a unique identity
* `message`: a text message
* `messageChangedCount`: the number of times the message text has changed since first being defined
* `description`: a text description of the message
* `descriptionChangedCount`: the number of times the description text has changed since first being defined

The first operation used is to define a new `Greeting`. To do so you `POST` a `JSON` object to the `/greetings` URI.

```
$ curl -i -X POST -H "Content-Type: application/json" -d '{"id":"","message":"Hey","messageChangedCount":"0","description":"Says Hey","descriptionChangedCount":"0" }' http://localhost:18080/greetings
```

The resource will respond with (only the id could be different):

```
HTTP/1.1 201 Created
Location: /greetings/242
Content-Length: 105

{"id":"242","message":"Hey","messageChangedCount":0,"description":"Says Hey","descriptionChangedCount":0}
```

Following this you may query the new `Greeting`. The `Location` of the new `Greeting` resource is `/greetings/{someId}`. Let's `GET` that resource.

```
$ curl -i -X GET http://localhost:18080/greetings/242
```

You should see the following:

```
HTTP/1.1 200 OK
Content-Length: 105

{"id":"242","message":"Hey","messageChangedCount":0,"description":"Says Hey","descriptionChangedCount":0}
```

Next `PATCH` the `Greeting` resource's `message`.

```
$ curl -i -X PATCH -H "Content-Type: application/json" -d '{"value":"Yo"}' http://localhost:18080/greetings/242/message
```

The resource responds with the following. Note that the `message` has changed to `"Yo"`, and the `messageChangedCount` is now `1`. Also notice that the `description` and the `descriptionChangedCount` remain unchanged.

```
HTTP/1.1 200 OK
Content-Length: 104

{"id":"242","message":"Yo","messageChangedCount":1,"description":"Says Hey","descriptionChangedCount":0}
```

Next `PATCH` the `Greeting` resource's `description`.

```
$ curl -i -X PATCH -H "Content-Type: application/json" -d '{"value":"Says Yo"}' http://localhost:18080/greetings/242/description
```

The resource responds with the following. Note that the `description` has changed to `"Says Yo"`, and the `descriptionChangedCount` is now `1`.

```
HTTP/1.1 200 OK
Content-Length: 103

{"id":"242","message":"Yo","messageChangedCount":1,"description":"Says Yo","descriptionChangedCount":1}
```

Now both the `message` and the `description` and the corresponding counts have all changed.

In this `Greeting` resource example there are various component sets involved. See the following source code.

```
io.vlingo.xoom.hello.Bootstrap

io.vlingo.xoom.hello.resource.GreetingResource

io.vlingo.xoom.hello.model.Greeting
io.vlingo.xoom.hello.model.GreetingEntity
io.vlingo.xoom.hello.model.GreetingState

io.vlingo.xoom.hello.infra.persistence.GreetingProjectionActor

io.vlingo.xoom.hello.infra.persistence.Queries
io.vlingo.xoom.hello.infra.persistence.QueriesActor

io.vlingo.xoom.hello.infra.persistence.* - lower-level persistence setup and storage access
```

Documentation for the above components is found in the following links.

[Starting the World](https://docs.vlingo.io/vlingo-actors#starting-and-terminating-the-actor-runtime)

[CQRS Command and Query Models](https://docs.vlingo.io/vlingo-lattice/entity-cqrs)

[StatefulEntity](https://docs.vlingo.io/vlingo-lattice/entity-cqrs#statefulentity-example)

[StateStore Persistence](https://docs.vlingo.io/vlingo-symbio/state-storage)

[Query Model Projections](https://docs.vlingo.io/vlingo-lattice/projections)

[Reactive Storage](https://docs.vlingo.io/vlingo-symbio)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.vlingo.io/getting-started/hello-world-1.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.