From 59b2324b502ca7e1d706170c26ce9b79f7784a14 Mon Sep 17 00:00:00 2001 From: rdhabalia Date: Mon, 28 Aug 2017 15:16:21 -0700 Subject: [PATCH] add namespace site section and fix headers --- site/_includes/explanations/non-persistent-topics.md | 12 ++++++------ .../getting-started/ConceptsAndArchitecture.md | 11 ++++++++++- site/docs/latest/getting-started/LocalCluster.md | 2 +- 3 files changed, 17 insertions(+), 8 deletions(-) diff --git a/site/_includes/explanations/non-persistent-topics.md b/site/_includes/explanations/non-persistent-topics.md index 6e383c2135bc4..a2cc5ae659ec5 100644 --- a/site/_includes/explanations/non-persistent-topics.md +++ b/site/_includes/explanations/non-persistent-topics.md @@ -9,12 +9,12 @@ Therefore, if you are using persistent delivery, messages are persisted to disk/ - In non-persistent topic, as soon as broker receives published message, it immediately delivers this message to all connected subscribers without persisting them into any storage. So, if subscriber gets disconnected with broker then broker will not be able to deliver those in-transit messages and subscribers will never be able to receive those messages again. Broker also drops a message for the consumer, if consumer does not have enough permit to consume message, or consumer TCP channel is not writable. Therefore, consumer receiver queue size (to accommodate enough permits) and TCP-receiver window size (to keep channel writable) should be configured properly to avoid message drop for that consumer. - Broker only allows configured number of in-flight messages per client connection. So, if producer tries to publish messages higher than this rate, then broker silently drops those new incoming messages without processing and delivering them to the subscribers. However, broker acknowledges with special message-id (`msg-id: -1:-1`) for those dropped messages to signal producer about the message drop. -### Performance +#### Performance Non-persistent messaging is usually faster than persistent messaging because broker does not persist messages and immediately sends ack back to producer as soon as that message deliver to all connected subscribers. Therefore, producer sees comparatively low publish latency with non-persistent topic. -## Client API +#### Client API A topic name will look like: @@ -25,10 +25,10 @@ non-persistent://my-property/us-west/my-namespace/my-topic Producer and consumer can connect to non-persistent topic in a similar way, as persistent topic except topic name must start with `non-persistent`. -Non-persistent topic supports all 3 different subscription-modes: **Exclusive**, **Shared**, **Failover** which are already explained in details at [GettingStarted](../../getting-started/ConceptsAndArchitecture.md). +Non-persistent topic supports all 3 different subscription-modes: **Exclusive**, **Shared**, **Failover** which are already explained in details at [GettingStarted](../../getting-started/ConceptsAndArchitecture). -### Consumer API +##### Consumer API ```java PulsarClient client = PulsarClient.create("pulsar://localhost:6650"); @@ -38,7 +38,7 @@ Consumer consumer = client.subscribe( "my-subscribtion-name"); ``` -### Producer API +##### Producer API ```java PulsarClient client = PulsarClient.create("pulsar://localhost:6650"); @@ -47,7 +47,7 @@ Producer producer = client.createProducer( "non-persistent://sample/standalone/ns1/my-topic"); ``` -### Broker configuration +#### Broker configuration Sometimes, there would be a need to configure few dedicated brokers in a cluster, to just serve non-persistent topics. diff --git a/site/docs/latest/getting-started/ConceptsAndArchitecture.md b/site/docs/latest/getting-started/ConceptsAndArchitecture.md index 836f9cd972b2f..fe93dcf52f584 100644 --- a/site/docs/latest/getting-started/ConceptsAndArchitecture.md +++ b/site/docs/latest/getting-started/ConceptsAndArchitecture.md @@ -82,9 +82,18 @@ As in other pub-sub systems, topics in Pulsar are named channels for transmittin | `persistent` | It identifies type of topic. Pulsar supports two kind of topics: persistent and non-persistent. In persistent topic, all messages are durably [persisted](#persistent-storage) on disk (that means on multiple disks unless the {% popover broker %} is {% popover standalone %}), whereas [non-persistent](#non-persistent-topics) topic does not persist message into storage disk. | | `property` | The topic's {% popover tenant %} within the instance. Tenants are essential to {% popover multi-tenancy %} in Pulsar and can be spread across clusters. | | `cluster` | Where the topic is located. Typically there will be one {% popover cluster %} for each geographical region or data center. | -| `namespace` | The administrative unit of the topic, which acts as a grouping mechanism for related topics. Most topic configuration is performed at the namespace level. Each property (tenant) can have multiple namespaces. | +| `namespace` | The administrative unit of the topic, which acts as a grouping mechanism for related topics. Most topic configuration is performed at the [namespace](#namespace) level. Each property (tenant) can have multiple namespaces. | | `topic` | The final part of the name. Topic names are freeform and have no special meaning in a Pulsar instance. | +{% include admonition.html type="success" title="No need to explicitly create new topics" +content="Application does not explicitly create the topic but attempting to write or receive message on a topic that does not yet exist, Pulsar will automatically create that topic under the [namespace](#namespace)." %} + +### Namespace +A namespace is a logical nomenclature within a property. A property can create multiple namespaces via [admin API](../../admin-api/namespaces#create). For instance, a property with different applications can create a separate namespace for each application. A namespace allows the application to create and manage a hierarchy of topics. +For e.g. `my-property/my-cluster/my-property-app1` is a namespace for the application `my-property-app1` in cluster `my-cluster` for `my-property`. +Application can create any number of [topics](#topics) under the namespace. + + ### Subscription modes A subscription is a named configuration rule that determines how messages are delivered to {% popover consumers %}. There are three available subscription modes in Pulsar: [exclusive](#exclusive), [shared](#shared), and [failover](#failover). These modes are illustrated in the figure below. diff --git a/site/docs/latest/getting-started/LocalCluster.md b/site/docs/latest/getting-started/LocalCluster.md index 0b4385292ed75..2e3858190c69c 100644 --- a/site/docs/latest/getting-started/LocalCluster.md +++ b/site/docs/latest/getting-started/LocalCluster.md @@ -33,7 +33,7 @@ If Pulsar has been successfully started, you should see `INFO`-level log message ``` {% include admonition.html type="success" title='Automatically created namespace' content=' -When you start a local standalone cluster, Pulsar will automatically create a `sample/standalone/ns1` namespace that you can use for development purposes. All Pulsar topics are managed within namespaces. For more info, see [Topics](../ConceptsAndArchitecture#Topics).' %} +When you start a local standalone cluster, Pulsar will automatically create a `sample/standalone/ns1` [namespace](../ConceptsAndArchitecture#namespace) that you can use for development purposes. All Pulsar topics are managed within namespaces. For more info, see [Topics](../ConceptsAndArchitecture#topics).' %} ## Testing your cluster setup