plan and usability updates

README.md

@@ -2,25 +2,39 @@
 IBM Message Hub is a scalable, distributed, high throughput message bus to unite your on-premise and off-premise cloud technologies. You can wire micro-services together using open protocols, connect stream data to analytics to realise powerful insight and feed event data to multiple applications to react in real time.
 
 This repository is for samples which interact with the Message Hub service. 
-Currently, there are samples for the Kafka, MQ Light and REST APIs.
+Currently, there are samples for the Kafka and MQ Light APIs.
 Information and instructions regarding the use of these samples can be found in their respective directories.
 
+## Aim of the Samples
+The aim of the samples is to help you get started with Message Hub within minutes. They are not production-ready applications but should give you useful pointers at how to build, package and deploy applications as well as how to make basic API calls against us with error handling. We did all the heavy lifting so you can focus on developing exciting code with value!
+
+## Provisioning your Message Hub Cluster
+In order to provision a Message Hub cluster, please visit the [IBM Cloud® catalog](https://console.stage1.bluemix.net/catalog/). Please also familiarise yourself with Message Hub and Apache Kafka basics and terminology. [Our documentation](https://console.bluemix.net/docs/services/MessageHub/) is a good starting point.
+
+
+### Pricing plans
+IBM Message Hub can be provisioned on IBM Cloud® in various pricing plans. Please refer to our [documentation](https://console.bluemix.net/docs/services/MessageHub/messagehub085.html#plan_choose) to help choose a plan that works for you.
+
+__Important Note__: Provisioning a Message Hub service in IBM Cloud® incurs a fee. Please review pricing before provisioning. The samples in this repository will create topic(s) on your behalf - creating a topic might also incur a fee. For more information, please consult the IBM Cloud® documentation if necessary.
+
+
+## Connecting to your Message Hub Cluster
+In each sample, we demonstrate a single connection path for both our Standard and Enterprise plans respectively. The aim was to get you started quickly. However your client's needs might be different. Therefore we wrote a [guide](https://console.bluemix.net/docs/services/MessageHub/messagehub127.html#connect_messagehub) that discusses credential generation in detail and showing you all possible ways of doing this.
+
+## Our APIs and Sample Applications
+
 ### Kafka API (recommended):
-* kafka-java-console-sample : Sample Java console application using the Message Hub Kafka API
-* kafka-java-liberty-sample : Sample IBM Websphere Liberty profile application using the Message Hub Kafka API
-* kafka-nodejs-console-sample : Sample Node.js console application using the Message Hub Kafka API
-* kafka-python-console-sample : Sample Python console application using the Message Hub Kafka API
+* [kafka-java-console-sample](/kafka-java-console-sample/README.md) : Sample Java console application using the Message Hub Kafka API
+* [kafka-java-liberty-sample](/kafka-java-liberty-sample/README.md) : Sample IBM Websphere Liberty profile application using the Message Hub Kafka API
+* [kafka-nodejs-console-sample](kafka-nodejs-console-sample/README.md) : Sample Node.js console application using the Message Hub Kafka API
+* [kafka-python-console-sample](/kafka-python-console-sample/README.md) : Sample Python console application using the Message Hub Kafka API
 
 ### MQ Light API:
-* mqlight : MQ Light samples in Java, Python, Node.js and Ruby
+* [mqlight](/mqlight/README.md) : MQ Light samples in Java, Python, Node.js and Ruby
 
-### REST API:
-* rest-nodejs-express-sample : Sample Node.js/Express application using the Message Hub REST API
+## Get Further Assistance
 
 If you have any issues, just ask us a question (tagged with message-hub) on [StackOverflow.com](http://stackoverflow.com/questions/tagged/message-hub).
 
 
-For more information regarding IBM Message Hub, [view the documentation on Bluemix](https://www.ng.bluemix.net/docs/services/MessageHub/index.html).
-
-__Important Note__: The samples in this repository will create topic(s) on your behalf - creating a topic incurs a fee. For more information, view the README files in each part of the
-repository and consult the Bluemix documentation if necessary.
+For more information regarding IBM Message Hub, [view the documentation on IBM Cloud](https://www.console.ng.bluemix.net/docs/services/MessageHub/index.html).

connecting_to_mhub.md

@@ -0,0 +1,133 @@
+# Connecting to Message Hub
+
+**TODO - Karen** ==> Charlie said: *`"Rename the 'Connecting to your cluster' section to 'Connecting to Message Hub' in the stage1 docs, and move down one level to being under About Message Hub"`*
+
+How you connect to your cluster varies according to whether you're using the Standard or Enterprise plan and also whether you're connecting from a Cloud Foundry application or from any other external client. You will need two pieces of information to connect to any of our APIs:
+
+- The APIs' endpoint URLs
+- An api key for authentication
+
+The steps to obtain these details can vary subtly and you should follow the appropriate steps below for your instance:
+
+## Prerequisites:
+### Provision a Message Hub instance
+
+It is a pre-requisite to [provision a Message Hub service instance](https://console.stage1.bluemix.net/docs/services/MessageHub/messagehub085.html#plan_choose). Please make sure you have already done so, noting your plan of choice. *Provisioning a Message Hub instance might incur a charge.* Afterwards, please refer to the sections below to obtain our API connection details:
+
+---
+
+## Standard Plan:
+
+Services provisioned using the Standard Plan are Cloud Foundry services. This means they are deployed into a Cloud Foundry organisation and space, and are grouped in the dashboard under the heading 'Cloud Foundry Services'. To connect an application, the method used depends on where the application is deployed:
+
+### Cloud Foundry applications
+
+For applications running inside Cloud Foundry, the application must be bound to the Message Hub service instance. Once bound, the connection details are then made available to the application in JSON format in the VCAP_SERVICES environment variable. Binding an application and service can be achieved using either the [web portal](https://console.bluemix.net/) or the [IBM Cloud CLI](https://console.bluemix.net/docs/cli/reference/bluemix_cli/get_started.html).
+
+**Web Portal**
+
+1) Make sure you're in the desired Cloud Foundry organization and space
+2) Locate your Cloud Foundry Application on the [Dashboard](https://console.stage1.bluemix.net/dashboard/apps/) or create one if you have not got one already by clicking on the "Create Resource" button
+3) Click on your application tile
+4) Select "Connections"
+5) Click "Create Connection"
+6) Select the Message Hub service tile you would like to bind to and click "Connect". You might need to restage your application for the changes to take effect.
+7) Click the "Runtime" tab on the left and select the "Environment variables" tab in the center. You can now verify your VCAP_SERVICES information. Your app can now access these as environment variables. 
+
+**IBM Cloud CLI**
+
+1) Make sure you're in the desired Cloud Foundry organization and space, you can navigate interactively by issuing `ibmcloud target -cf`
+2) Find your app: `ibmcloud app list`. If you have a manifest file, you can create a new app by running `ibmcloud app push`
+3) Find your service: `ibmcloud service list`
+4) Bind your app to the service: `ibmcloud service bind <your app's name> <your service's name>`
+5) Verify that the VCAP_SERVICES environment variables are available in your application runtime. You can do this by calling `ibmcloud app env <your app's name>`. 
+6) Pass these credentials to your application.
+
+You might need to restage your application for the changes to take effect.
+
+### External Applications
+
+For applications running outside of Cloud Foundry, credentials are generated by creating a Service Key. Once obtained, the details of the key then need to be manually passed to your application via mechanisms of your own choice:
+
+**Portal**
+
+1) Make sure you're in the desired Cloud Foundry organization and space
+2) Locate your Cloud Foundry Message Hub service on the [Dashboard](https://console.stage1.bluemix.net/dashboard)
+3) Click on your service tile
+4) Select "Service Credentials"
+5) Click "New Credential"
+6) Fill in the details for your new credential such as name and click "Add". A new credential appears in the credentials list.
+7) By clicking on this credential (view credential), the details are revealed in JSON format.
+8) Pass these credentials to your application.
+
+**IBM Cloud CLI**
+
+1) Make sure you're in the desired Cloud Foundry organization and space, you can navigate interactively by issuing `ibmcloud target -cf`
+2) Find your service: `ibmcloud service list`
+3) Either create a service key: `ibmcloud service key-create <your service's name> <name of new service key>` or use an existing service key: `ibmcloud service keys <your service's name>`
+4) Get the details for the key:  `ibmcloud service key-show <your service's name> <name of service key>` . This returns the service key details in JSON format.
+5) Pass these credentials to your application.
+
+---
+
+## Enterprise Plan:
+
+Services provisioned using the Enterprise Plan are grouped in the dashboard under the heading 'Services'. The Enterprise Plan is [IAM enabled](https://console.bluemix.net/docs/iam/quickstart.html#getstarted). You don't need to understand IAM to get started but some knowledge is recommended, should you wish to [secure your Message Hub service](https://console.bluemix.net/docs/services/MessageHub/messagehub124.html#security).
+
+In this section, we're going to explain the steps involved in binding your application and/or obtaining Service Keys for your service. *Please note that in order to be authorized to create topics, your application or Service Key has to be of `Manager` access role.*
+
+To connect an application, the method used depends on where the application is deployed:
+
+### Cloud Foundry Applications
+
+Your application must be bound to the Message Hub service instance. In order to bind a Cloud Foundry Application to a non-Cloud Foundry Service with One Cloud, a Cloud Foundry Service Alias needs to be created first. This alias is then referenced from your Cloud Foundry Application when binding.
+
+Once bound, the connection details are then made available to the application in JSON format through the VCAP_SERVICES environment variable. Binding an application and service can be achieved using either the [web portal](https://console.bluemix.net/) or the [IBM Cloud CLI](https://console.bluemix.net/docs/cli/reference/bluemix_cli/get_started.html).
+
+**Portal**
+1) Make sure you're in the desired Cloud Foundry organization and space
+2) Locate your Cloud Foundry Application on the [Dashboard](https://console.stage1.bluemix.net/dashboard/apps/) or create one if you have not got one already by clicking on the "Create Resource" button
+3) Click on your application tile
+4) Select "Connections"
+5) Click "Create Connection"
+6) Select the Message Hub service tile you would like to bind to and click "Connect"
+7) The above step will create a Cloud Foundry Service Alias for your Message Hub service and bind your application to this alias afterwards. On the portal, this happens automatically but on the IBM Cloud CLI, a separate manual step is required. You might need to restage your application for the changes to take effect.
+8) Click the "Runtime" tab on the left and select the "Environment variables" tab in the center. You can now verify your VCAP_SERVICES information. Your app can now access these as environment variables. 
+
+**IBM Cloud CLI**
+1) Make sure you're in the desired Cloud Foundry organization and space, you can navigate interactively by issuing `ibmcloud target -cf`
+2) Find your app: `ibmcloud app list`. If you have a manifest file, you can create a new app by running `ibmcloud app push`. As the app is not bound to Message Hub yet, it will not be able to establish a connection. Therefore it is recommended to push the application with the ` --no-start` parameter to avoid unnecessary connection failures.
+3) Find your service: `ibmcloud resource service-instances`
+4) Create a Cloud Foundry Service Alias: `ibmcloud resource service-alias-create <alias_name> --instance-name <your service's name>`
+5) Bind your app to the Service Alias created above: `ibmcloud service bind <your app's name> <alias_name>`. Alternatively you can update your manifest file and re-push the application.
+6) Verify that the VCAP_SERVICES environment variable is available in your application runtime. You can do this by calling `ibmcloud app env <your app's name>`.
+7) Pass these credentials to your application.
+
+You might need to restage your application for the changes to take effect.
+
+
+### External Applications
+
+For applications running outside of Cloud Foundry, credentials are generated by creating a Service Key. Once obtained, the details of the key then need to be manually passed to your application via mechanisms of your own choice:
+
+**Portal**
+1) Locate your Message Hub service on the [Dashboard](https://console.stage1.bluemix.net/dashboard)
+2) Click on your service tile
+3) Select "Service Credentials"
+4) Click "New Credential"
+5) Fill in the details for your new credential and click "Add". A new credential will appear in the credentials list.
+6) By clicking on this credential (view credential), the details are revealed in JSON format.
+7) Pass these credentials to your application. Make sure your application parses the details.
+
+**IBM Cloud CLI**
+1) Find your service: `ibmcloud resource service-instances`
+2) Create a Service Key: `ibmcloud resource service-key-create <key_name> <key_role> --instance-name <your_service_name>`
+3) Print the Service Key: `ibmcloud resource service-key <key_name>`
+4) Pass these credentials to your application. Make sure your application parses the details.
+
+**TODO - Karen** ==> Charlie gave me the instructions below, however, I'm not sure it's supposed to be in this section as it's not about how to use IBM Cloud but about how to use Kafka? Maybe the section he highlights could be copied over and referenced/linked from here? I think this is too specific...
+
+Charlie said:
+
+*`"Add some info describing how to take the information made available from above e.g. like the info in the Connecting a client to the Kafka API section of the alpha docs on stage 1? https://console.stage1.bluemix.net/docs/services/MessageHub/messagehub122.html#alpha_about "`*
+

java/message-hub-liberty-sample/lib-message-hub/README.md

@@ -0,0 +1 @@
+../../../kafka-0.9/message-hub-login-library/README.md

java/message-hub-liberty-sample/lib-message-hub/messagehub.login-1.0.0.jar

@@ -0,0 +1 @@
+../../../kafka-0.9/message-hub-login-library/messagehub.login-1.0.0.jar

java/message-hub-liberty-sample/lib-message-hub/messagehub.login-1.0.0.jar.asc

@@ -0,0 +1 @@
+../../../kafka-0.9/message-hub-login-library/messagehub.login-1.0.0.jar.asc