Skip to content

Commit 3fe2f36

Browse files
mendonkmendonk
committed
Initial file structure, antora, and content build for streaming docs site.
1 parent b131997 commit 3fe2f36

13 files changed

+2118
-7
lines changed

‎antora.yml

Lines changed: 98 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,104 @@ start_page: starlight-for-jms::index.adoc
55

66
asciidoc:
77
attributes:
8+
source-highlighter: highlightjs
9+
page-pagination: ''
10+
sectanchors: ''
11+
sectlinks: ''
12+
id-prefix: ''
13+
id-separator: '-'
14+
15+
starlight_jms: 'Starlight for JMS'
16+
jms_repo: 'https://github.com/datastax/pulsar-jms/'
17+
jms_repo_frag: 'datastax/'
18+
product_version: '3.x'
19+
20+
company: 'DataStax'
21+
product: 'Product'
22+
product_name: 'Product'
23+
evalproduct: 'DB Classic'
24+
database: 'Astra DB'
25+
astra_db: 'Astra DB'
26+
astra_generic: 'Astra'
27+
classic: 'classic'
28+
classic_cap: 'Classic'
29+
serverless: 'serverless'
30+
serverless_cap: 'Serverless'
31+
astra_stream: 'Astra Streaming'
32+
advanced: 'no'
33+
34+
stargate-docker-tag: v1.0.41
35+
stargate-docker-tag-3x: v1.0.41
36+
stargate-docker-tag-40: v1.0.41
37+
stargate-docker-tag-68: v1.0.40
38+
cass-tag-3x: '3.11'
39+
cass-alt-tag-3x: '3_11'
40+
cass-tag-40: '4.0'
41+
cass-alt-tag-40: '4_0'
42+
dse-server-tag-68: '6.8.9'
43+
dse-tag-68: '6.8'
44+
dse-alt-tag-68: '68'
45+
46+
ASTRA_CLUSTER_ID: '8319febd-e7cf-4595-81e3-34f45d332d2a'
47+
ASTRA_REGION: 'us-east1'
48+
ASTRA_USERNAME: 'polandll'
49+
ASTRA_PASSWORD: '12345abcd'
50+
51+
auth_token: '$ASTRA_DB_APPLICATION_TOKEN'
52+
base_auth_url: 'http://$ASTRA_CLUSTER_ID-$ASTRA_REGION.apps.astra.datastax.com:8081'
53+
base_auth_api_path: '/v1/auth'
54+
cass_user: 'cassandra' # switch to auth_username
55+
cass_passwd: 'cassandra' # switch to auth_password
56+
57+
base_rest_url: 'https://$ASTRA_CLUSTER_ID-$ASTRA_REGION.apps.astra.datastax.com'
58+
base_doc_url: 'https://$ASTRA_CLUSTER_ID-$ASTRA_REGION.apps.astra.datastax.com'
59+
base_graphql_url: 'https://$ASTRA_CLUSTER_ID-$ASTRA_REGION.apps.astra.datastax.com:8080'
60+
61+
base_rest_schema: '/api/rest/v2/schemas/keyspaces'
62+
base_doc_schema: '/api/rest/v2/schemas/namespaces'
63+
base_gql_schema: '/api/graphql-schema'
64+
65+
base_gql_admin: '/api/graphql-admin'
66+
67+
base_rest_api: '/api/rest/v2/keyspaces'
68+
base_doc_api: '/api/rest/v2/namespaces'
69+
base_gql_api: '/api/graphql'
70+
71+
rkeyspace: 'users_keyspace'
72+
rkeyspace-dcs: 'users_keyspace-dcs'
73+
rpartitionkey: 'firstname'
74+
rclusteringkey: 'lastname'
75+
rtable: 'users'
76+
user1fn: 'Mookie'
77+
user1ln: 'Betts'
78+
user2fn: 'Janesha'
79+
user2ln: 'Doesha'
80+
81+
namespace: 'myworld'
82+
collection: 'fitness'
83+
user1: 'Janet'
84+
user2: 'Joey'
85+
user2a: 'Joseph'
86+
user3: 'Martha'
87+
88+
gkeyspace: 'library'
89+
gtable1: 'book'
90+
gtable2: 'reader'
91+
92+
support_url: 'https://houston.datastax.com/hc/requests/new'
93+
astra_docs_base_url: 'https://docs.datastax.com/en/astra/docs'
94+
95+
# The "glossary-url" attribute below is used by writers when linking to a
96+
# term in the glossary. Referencing this attribute in an adoc file will
97+
# automatically insert the root URL where the glossary pages are located.
98+
# For example, the following syntax will generate a link to the glossary
99+
# page for "agent": {glossary-url}agent[agent,window="_blank"]
100+
glossary-url: 'https://docs.datastax.com/en/glossary/docs/index.html#'
101+
102+
# Bsys requires the URLs of the content source repos of the current docset
103+
# to be listed as attributes in the site-publish playbook in the form
104+
# "<repo-name>: 'ssh://github.com/<org-name>/<repo-name>.git'".
105+
starlight-docs: 'ssh://github.com/datastax/starlight-docs.git'
8106

9107
nav:
10108
- modules/ROOT/nav.adoc

‎modules/ROOT/.DS_Store

6 KB
Binary file not shown.

‎modules/ROOT/nav.adoc

Lines changed: 13 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,14 @@
1-
* xref:index.adoc[Overview]
2-
3-
* JMS Migration
4-
1+
* Getting Started
2+
** xref:index.adoc[About {starlight_jms}]
3+
** xref:pulsar-jms-install.adoc[Installation]
4+
** xref:pulsar-jms-mappings.adoc[Mapping Pulsar concepts to JMS]
5+
** xref:pulsar-jms-implementation.adoc[Implementation details]
6+
** xref:pulsar-jms-server-side-filters.adoc[Server-side filters]
7+
** xref:pulsar-jms-batch-ack.adoc[Batch index acknowledgement]
8+
* Guides and Examples
9+
** xref:pulsar-jms-quickstart-sa.adoc[Pulsar standalone quick start]
10+
** xref:pulsar-jms-quickstart-astra.adoc[Astra Streaming quick start]
511
* Reference
6-
7-
* Examples
12+
** xref:pulsar-jms-reference.adoc[{starlight_jms} Reference]
13+
** xref:pulsar-jms-faq.adoc[FAQs]
14+
** {jms_repo}[Github repo,window=_blank]

‎modules/ROOT/pages/index.adoc

Lines changed: 28 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,28 @@
1-
Welcome to the S4J site
1+
= About {starlight_jms}
2+
3+
:page-tag: starlight-jms,planner,dev,admin,pulsar,jms
4+
5+
{starlight_jms} is the first highly compliant JMS implementation designed to run on a modern streaming platform. It allows enterprises to take advantage of the scalability and resiliency of a modern streaming platform to run their existing JMS applications. Because Apache Pulsar™ is open-source and cloud-native, {starlight_jms} enables enterprises to move their JMS applications to run on-premises and in any cloud environment.
6+
7+
== Key Features
8+
9+
{starlight_jms} key features include:
10+
11+
* *Blazing fast JMS performance*: Achieve 1 million JMS messages per second with 99 percentile publish to acknowledge latency of less than 10 ms.
12+
* *Drop-in replacement for existing JMS applications*: Supports JMS/Jakarta 2.0 and is backwards compatible with JMS 1.1. 100% pass rate on JMS compliance test for supported features.
13+
* *Horizontally scalable JMS*: Apache Pulsar is a horizontally scaled distributed streaming platform. You can scale up or down without operational hassles. Pulsar separates compute from storage, which means you can scale those dimensions independently, as required. Pulsar supports offloading old data to object storage for practically infinite storage capacity.
14+
* *Reduced total cost of ownership*: Because Apache Pulsar is natively multi-tenant and high performance, you can consolidate JMS applications spread across multiple legacy JMS brokers onto a single Apache Pulsar installation. And since Pulsar is easily horizontally scaled, you don’t need to overprovision.
15+
* *Future proof*: Apache Pulsar can support traditional messaging workloads, but it can also support modern streaming use cases such as log collection, microservices integration, event streaming, event sourcing. New workloads can run alongside Legacy JMS applications.
16+
* *Open source to avoid lock in*: {starlight_jms} and Apache Pulsar are 100% open source. You can run on-premise, in any cloud provider, or in Kubernetes.
17+
* *Adds message replay to JMS*: Apache Pulsar natively supports message retention and replay. This allows applications using Fast JMS for Apache Pulsar to travel back in time and replay previously consumed messages to recover from misconfiguration issues, recover from bugs in application code, and test new applications against real data.
18+
19+
== What's next?
20+
21+
* *xref:pulsar-jms-quickstart-sa.adoc[]*: Create a simple command line Java JMS client that connects to a local Pulsar installation.
22+
* *xref:pulsar-jms-quickstart-astra.adoc[]*: Create a simple command line Java JMS client that connects to an Astra Streaming instance.
23+
* *xref:pulsar-jms-install.adoc[]*: Install {starlight_jms} in your own JMS project.
24+
* *xref:pulsar-jms-mappings.adoc[]*: Understand Pulsar concepts in the context of JMS.
25+
* *xref:pulsar-jms-implementation.adoc[]*: Understand key implementation details for {starlight_jms}.
26+
* *xref:pulsar-jms-faq.adoc[]*: Frequently asked questions about {starlight_jms}.
27+
* *xref:pulsar-jms-reference.adoc[]*: {starlight_jms} configuration reference.
28+
* *{jms_repo}[{starlight_jms} Github repo,window=_blank]*

‎modules/ROOT/pages/pulsar-jms-batch-ack.adoc

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
= Batch index acknowledgement
2+
3+
{starlight_jms} version {product_version} improves acknowledgement of batched messages by supporting the tracking of 'ack' status by *batch index*. +
4+
5+
By default, filtering works on the *entry* level in Pulsar. An *entry* is a *single message* or a *single batch of messages*. The client will not filter out a few messages in a batch; it either passes completely or fails completely. +
6+
7+
With *batch index acknowledgement*, when the broker dispatches messages, it will carry the batch index that has been acknowledged. The client will filter out batch indexes that have been acked. +
8+
9+
The client sends the batch index ack information to the broker, so the broker can maintain the batch index ack status. +
10+
11+
This approach requires cooperation between the client and broker, so we must modify both `broker.conf` and the `consumerConfig` JMS client property to enable batch acknowledgement. +
12+
13+
DataStax *strongly recommends* these configurations for increased efficiency, whether using *broker-side* or *client-side* selectors.
14+
15+
== Enable batch index acknowledgement
16+
17+
. Add the configuration property `acknowledgmentAtBatchIndexLevelEnabled=true` to `broker.conf`:
18+
+
19+
[source,java]
20+
----
21+
acknowledgmentAtBatchIndexLevelEnabled=true
22+
----
23+
24+
. Set the `consumerConfig` property on the JMS client by adding `consumerConfig.put("batchIndexAckEnabled", true);` to `consumerConfig` in the ConnectionFactory configuration:
25+
+
26+
[source,java]
27+
----
28+
Map<String, Object> properties = new HashMap<>();
29+
properties.put("webServiceUrl", cluster.getAddress());
30+
Map<String, Object> consumerConfig = new HashMap<>();
31+
consumerConfig.put("batchIndexAckEnabled", true);
32+
properties.put("consumerConfig", consumerConfig);
33+
try (PulsarConnectionFactory factory = new PulsarConnectionFactory(properties));
34+
----
35+
36+
== What's next?
37+
38+
For more on *server-side filtering*, see xref:pulsar-jms-server-side-filters.adoc[Server side filters]. +
39+
For more on acknowledgements in {starlight_jms}, see xref:pulsar-jms-mappings.adoc#consumer-mappings[Consumer Mappings].
40+
41+
42+

‎modules/ROOT/pages/pulsar-jms-faq.adoc

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
= {starlight_jms} FAQs
2+
3+
:page-tag: starlight-jms,planner,dev,admin,pulsar,jms
4+
5+
Answers to the (arguably) most common {starlight_jms} questions.
6+
7+
== What is the pricing for {starlight_jms}?
8+
9+
{starlight_jms} is free open-source software. Enterprise support is available through https://www.datastax.com/products/luna-streaming[Luna Streaming,window=_blank], the DataStax commercial support offering for Apache Pulsar™.
10+
11+
== How is {starlight_jms} licensed?
12+
13+
{starlight_jms} is licensed under https://www.apache.org/licenses/LICENSE-2.0.txt[Apache version 2.0,window=_blank].
14+
15+
== How can I use {starlight_jms} in a JakartaEE® or JavaEE® application?
16+
17+
You can use the `resourceAdapter` {jms_repo}blob/master/resource-adapter[here,window=_blank].
18+
19+
== How can I run the Test Compatibility Kit (TCK)
20+
21+
You can download the TCK https://jakarta.ee/specifications/messaging/2.0/[here,window=_blank]. The repository contains a copy of the TCK that automates the execution of the tests.
22+
23+
In the tck-executor module you'll find:
24+
25+
* The Java Code needed to initialize the TCK, `JNDIInitialContextFactory.java`.
26+
* The configuration file for the TCK runner, `ts.jte`.
27+
* A file that contains the excluded tests that cannot pass with this client, `ts.jtx`
28+
* Scripts to run Apache Pulsar 2.7.1, configure the Transaction Coordinator, and prepare for the execution of the TCK.
29+
30+
To build the package, run unit tests, and run the TCK:
31+
32+
[source,language-bash]
33+
----
34+
mvn clean install -Prun-tck
35+
----
36+
37+
To run only the TCK:
38+
39+
[source,language-bash]
40+
----
41+
mvn clean install -Prun-tck -am -DskipTests -pl tck-executor
42+
----
43+
44+
IMPORTANT: Globally unique subscription names are not supported so the corresponding tests are skipped.
45+
46+
== Where can I find additional integration examples?
47+
48+
We've provided the following integration examples:
49+
50+
* {jms_repo}blob/master/examples/spring[Spring Boot®,window=_blank]
51+
* {jms_repo}blob/master/examples/payara-micro[Payara Micro®,window=_blank]
52+
* {jms_repo}blob/master/resource-adapter-tests[Apache TomEE®,window=_blank]
53+
54+
== How can I build {starlight_jms} from source?
55+
56+
If you'd like to fork or contribute to {starlight_jms}:
57+
58+
. Clone the git repo:
59+
+
60+
[source,language-bash]
61+
----
62+
git clone [email protected]:datastax/pulsar-jms.git
63+
----
64+
65+
. Build using Maven:
66+
+
67+
[source,language-bash]
68+
----
69+
mvn clean install
70+
----
71+
72+
== Where can I find additional information on JMS?
73+
74+
Refer to the https://jakarta.ee/specifications/messaging/2.0/[official JMS documentation,window=_blank] in order to learn about JMS.
75+
This https://javaee.github.io/jms-spec/[website,window=_blank] is useful as well as it contains the former JMS 2.0 specifications before the Jakarta transition.
76+
77+
== What's next?
78+
79+
* *xref:pulsar-jms-quickstart-sa.adoc[]*: Create a simple command line Java JMS client that connects to a local Pulsar installation.
80+
* *xref:pulsar-jms-quickstart-astra.adoc[]*: Create a simple command line Java JMS client that connects to an Astra Streaming instance.
81+
* *xref:pulsar-jms-install.adoc[]*: Install {starlight_jms} in your own JMS project.
82+
* *xref:pulsar-jms-mappings.adoc[]*: Understand Pulsar concepts in the context of JMS.
83+
* *xref:pulsar-jms-implementation.adoc[]*: Understand key implementation details for {starlight_jms}.
84+
* *xref:pulsar-jms-reference.adoc[]*: {starlight_jms} configuration reference.
85+
* *{jms_repo}[{starlight_jms} Github repo,window=_blank]*

0 commit comments

Comments
 (0)