Title:        Hedwig Console
Notice: 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":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.
        .
        .

h1. Hedwig Console

Apache Hedwig provides a console client, which allows users and administrators to interact with a hedwig cluster. 

h2. Connecting to hedwig cluster

Hedwig console client is shipped with hedwig server package.

p. To start the console client:

 @hedwig-server/bin/hedwig console@

p. By default, the console client connects to hub server on localhost. If you want the console client to connect to a different hub server, you can override following environment variables.

| @HEDWIG_CONSOLE_SERVER_CONF@ | Path of a hub server configuration file. Override to make hedwig console client connect to correct zookeeper cluster. |
| @HEDWIG_CONSOLE_CLIENT_CONF@ | Path of a hedwig client configuration file. Override to make hedwig console client communicate with correct hub servers. |

p. Once connected, you should see something like:

<pre>
Connecting to zookeeper/bookkeeper using HedwigAdmin

Connecting to default hub server localhost/127.0.0.1:4080
Welcome to Hedwig!
JLine support is enabled
JLine history support is enabled
[hedwig: (standalone) 16] 
</pre>

p. From the shell, type __help__ to get a list of commands that can be executed from the client:

<pre>
[hedwig: (standalone) 16] help
HedwigConsole [options] [command] [args]

Available commands:
        pub
        sub
        closesub
        unsub
        rmsub
        consume
        consumeto
        pubsub
        show
        describe
        readtopic
        set
        history
        redo
        help
        quit
        exit

Finished 0.0020 s.
</pre>

p. If you want to know detail usage for each command, type __help {command}__ in the shell. For example:

<pre>
[hedwig: (standalone) 17] help pub
pub: Publish a message to a topic in Hedwig
usage: pub {topic} {message}

  {topic}   : topic name.
              any printable string without spaces.
  {message} : message body.
              remaining arguments are used as message body to publish.

Finished 0.0 s.
</pre>

h2. Commands

All the available commands provided in hedwig console could be categorized into three groups. They are __interactive commands__, __admin commands__, __utility commands__.

h3. Interactive Commands

p. Interactive commands are used by users to communicate with a hedwig cluster. They are __pub__, __sub__, __closesub__, __unsub__, __consume__ and __consumeto__.

p. These commands are quite simple and have same semantics as the API provided in hedwig client.

h3.  Admin Commands

p. Admin commands are used by administrators to operate or debug a hedwig cluster. They are __show__, __describe__, __pubsub__ and __readtopic__.

p. __show__ is used to list all available hub servers or topics in the cluster.

p. You could use __show__ to list hub servers to know how many hub servers are alive in the cluster.

<pre>
[hedwig: (standalone) 27] show hubs
Available Hub Servers:
        192.168.1.102:4080:9876 :       0
Finished 0.0040 s.
</pre>

p. Also, you could use __show__ to list all topics. If you have a lot of topics on the clusters, this command will take a long time to run.

<pre>
[hedwig: (standalone) 28] show topics
Topic List:
[mytopic]
Finished 0.0020 s.
</pre>

p. To see the details of a topic, run __describe__. This shows the metadata of a topic, including topic owner, persistence info, subscriptions info.

<pre>
[hedwig: (standalone) 43] describe topic mytopic
===== Topic Information : mytopic =====

Owner : 192.168.1.102:4080:9876

>>> Persistence Info <<<
Ledger 3 [ 1 ~ 9 ]

>>> Subscription Info <<<
Subscriber mysub : consumeSeqId: local:0

Finished 0.011 s.
</pre>

p. When you are run the __describe__ command, you should keep in mind that __describe__ command reads the metadata from __ZooKeeper__ directly, so the subscription info might not be completely up to date due to the fact that hub servers update the subscription metadata lazily.

p. The __readtopic__ command is useful to see which messages have not been consumed by the client.

<pre>
[hedwig: (standalone) 46] readtopic mytopic

>>>>> Ledger 3 [ 1 ~ 9] <<<<<

---------- MSGID=LOCAL(1) ----------
MsgId:     LOCAL(1)
SrcRegion: standalone
Message:

hello

---------- MSGID=LOCAL(2) ----------
MsgId:     LOCAL(2)
SrcRegion: standalone
Message:

hello 2

---------- MSGID=LOCAL(3) ----------
MsgId:     LOCAL(3)
SrcRegion: standalone
Message:

hello 3

...
</pre>

p. __pubsub__ is another useful command for administrators. It can be used to test availability and functionality of a cluster. It generates a temporary subscriber id with the current timestamp, subscribes to the given topic using generated subscriber id, publishes a message to given topic and testes whether the subscriber received the message.

<pre>
[hedwig: (standalone) 48] pubsub testtopic testsub- 10 test message for availability
Starting PUBSUB test ...
Sub topic testtopic, subscriber id testsub--1338126964504
Pub topic testtopic : test message for availability-1338126964504
Received message : test message for availability-1338126964504
PUBSUB SUCCESS. TIME: 377 MS
Finished 0.388 s.
</pre>

h3. Utility Commands

p. Utility Commands are __help__, __history__, __redo__, __quit__ and __exit__.

p. __quit__ and __exit__ are used to exit console, while __history__ and __redo__ are used to manage the history of commands executed in the shell.