Skip to content

Commit

Permalink
[docs] Fix link issues for topics (apache#8478)
Browse files Browse the repository at this point in the history
### Motivation
Restructure topics content in "Admin API" section, so need to update links.

### Modifications
Update links only in the `docs` folder. Will apply the changes in different versions after all updates are finished.

Related PRs:  
apache#8375 
apache#8388
apache#8462
apache#8481
  • Loading branch information
Jennifer88huang-zz authored Nov 8, 2020
1 parent 2c9fe27 commit d7f6545
Show file tree
Hide file tree
Showing 9 changed files with 21 additions and 97 deletions.
4 changes: 1 addition & 3 deletions site2/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -77,11 +77,9 @@ The markdown files placed in the `docs` directory adopt a flat structure.
│   ├── admin-api-brokers.md
│   ├── admin-api-clusters.md
│   ├── admin-api-namespaces.md
│   ├── admin-api-non-persistent-topics.md
│   ├── admin-api-overview.md
│   ├── admin-api-partitioned-topics.md
│   ├── admin-api-permissions.md
│   ├── admin-api-persistent-topics.md
│   ├── admin-api-topics.md
│   ├── admin-api-tenants.md
│   ├── administration-dashboard.md
│   ├── administration-geo.md
Expand Down
6 changes: 4 additions & 2 deletions site2/docs/admin-api-non-partitioned-topics.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
---
id: admin-api-non-partitioned-topics
title: Managing non-partitioned topics
sidebar_label: Topics2
---
sidebar_label: Non-partitioned topics
---

For details of the content, refer to [manage topics](admin-api-topics.md).
4 changes: 3 additions & 1 deletion site2/docs/admin-api-non-persistent-topics.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,4 +2,6 @@
id: admin-api-non-persistent-topics
title: Managing non-persistent topics
sidebar_label: Non-Persistent topics
---
---

For details of the content, refer to [manage topics](admin-api-topics.md).
4 changes: 3 additions & 1 deletion site2/docs/admin-api-partitioned-topics.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,4 +2,6 @@
id: admin-api-partitioned-topics
title: Managing partitioned topics
sidebar_label: Partitioned topics
---
---

For details of the content, refer to [manage topics](admin-api-topics.md).
7 changes: 7 additions & 0 deletions site2/docs/admin-api-persistent-topics.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
---
id: admin-api-persistent-topics
title: Managing persistent topics
sidebar_label: Persistent topics
---

For details of the content, refer to [manage topics](admin-api-topics.md).
2 changes: 1 addition & 1 deletion site2/docs/cookbooks-non-persistent.md
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@ $ bin/pulsar-client produce non-persistent://public/default/example-np-topic \
--messages "This message will be stored only in memory"
```

> For a more thorough guide to non-persistent topics from an administrative perspective, see the [Non-persistent topics](admin-api-non-persistent-topics.md) guide.
> For a more thorough guide to non-persistent topics from an administrative perspective, see the [Non-persistent topics](admin-api-topics.md) guide.
## Enabling

Expand Down
88 changes: 1 addition & 87 deletions site2/docs/cookbooks-partitioned.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,90 +3,4 @@ id: cookbooks-partitioned
title: Partitioned topics
sidebar_label: Partitioned Topics
---

By default, Pulsar topics are served by a single broker. Using only a single broker limits a topic's maximum throughput. *Partitioned topics* are a special type of topic that can span multiple brokers and thus allow for much higher throughput. For an explanation of how partitioned topics work, see the [Partitioned Topics](concepts-messaging.md#partitioned-topics) concepts.

You can publish to partitioned topics using Pulsar client libraries and you can [create and manage](#managing-partitioned-topics) partitioned topics using Pulsar [admin API](admin-api-overview.md).

## Publish to partitioned topics

When publishing to partitioned topics, you do not need to explicitly specify a [routing mode](concepts-messaging.md#routing-modes) when you create a new producer. If you do not specify a routing mode, the round robin route mode is used. Take [Java](#java) as an example.

Publishing messages to partitioned topics in the Java client works much like [publishing to normal topics](client-libraries-java.md#using-producers). The difference is that you need to specify either one of the currently available message routers or a custom router.

### Routing mode

You can specify the routing mode in the ProducerConfiguration object that you use to configure your producer. Three options are available:

* `SinglePartition`
* `RoundRobinPartition`
* `CustomPartition`

The following is an example:

```java
String pulsarBrokerRootUrl = "pulsar://localhost:6650";
String topic = "persistent://my-tenant/my-namespace/my-topic";

PulsarClient pulsarClient = PulsarClient.builder().serviceUrl(pulsarBrokerRootUrl).build();
Producer<byte[]> producer = pulsarClient.newProducer()
.topic(topic)
.messageRoutingMode(MessageRoutingMode.SinglePartition)
.create();
producer.send("Partitioned topic message".getBytes());
```

### Custom message router

To use a custom message router, you need to provide an implementation of the {@inject: javadoc:MessageRouter:/client/org/apache/pulsar/client/api/MessageRouter} interface, which has just one `choosePartition` method:

```java
public interface MessageRouter extends Serializable {
int choosePartition(Message msg);
}
```

The following router routes every message to partition 10:

```java
public class AlwaysTenRouter implements MessageRouter {
public int choosePartition(Message msg) {
return 10;
}
}
```

With that implementation in hand, you can send

```java
String pulsarBrokerRootUrl = "pulsar://localhost:6650";
String topic = "persistent://my-tenant/my-cluster-my-namespace/my-topic";

PulsarClient pulsarClient = PulsarClient.builder().serviceUrl(pulsarBrokerRootUrl).build();
Producer<byte[]> producer = pulsarClient.newProducer()
.topic(topic)
.messageRouter(new AlwaysTenRouter())
.create();
producer.send("Partitioned topic message".getBytes());
```

### How to choose partitions when using a key
If a message has a key, it supersedes the round robin routing policy. The following example illustrates how to choose partition when you use a key.

```java
// If the message has a key, it supersedes the round robin routing policy
if (msg.hasKey()) {
return signSafeMod(hash.makeHash(msg.getKey()), topicMetadata.numPartitions());
}

if (isBatchingEnabled) { // if batching is enabled, choose partition on `partitionSwitchMs` boundary.
long currentMs = clock.millis();
return signSafeMod(currentMs / partitionSwitchMs + startPtnIdx, topicMetadata.numPartitions());
} else {
return signSafeMod(PARTITION_INDEX_UPDATER.getAndIncrement(this), topicMetadata.numPartitions());
}
```

## Manage partitioned topics

You can use Pulsar [admin API](admin-api-overview.md) to create and manage [partitioned topics](admin-api-partitioned-topics.md).
For details of the content, refer to [manage topics](admin-api-topics.md).
2 changes: 1 addition & 1 deletion site2/docs/developing-binary-protocol.md
Original file line number Diff line number Diff line change
Expand Up @@ -442,7 +442,7 @@ reconnect a producer or a consumer. Lookup is used to discover which particular
broker is serving the topic we are about to use.

Lookup can be done with a REST call as described in the
[admin API](admin-api-persistent-topics.md#lookup-of-topic)
[admin API](admin-api-topics.md#lookup-of-topic)
docs.

Since Pulsar-1.16 it is also possible to perform the lookup within the binary
Expand Down
1 change: 0 additions & 1 deletion site2/website/sidebars.json
Original file line number Diff line number Diff line change
Expand Up @@ -129,7 +129,6 @@
"cookbooks-compaction",
"cookbooks-deduplication",
"cookbooks-non-persistent",
"cookbooks-partitioned",
"cookbooks-retention-expiry",
"cookbooks-encryption",
"cookbooks-message-queue",
Expand Down

0 comments on commit d7f6545

Please sign in to comment.