Add GraphQL News Broadcasting use case example

[Sachindu-Nethmin]

Purpose

The purpose of this PR is to add a new comprehensive use case to the documentation titled "GraphQL News Broadcasting Service".

• Defining custom data types (Records) visually.
• Implementing GraphQL Mutations to handle data input.
• Configuring GraphQL Subscriptions using Service Classes to broadcast real-time updates.

Goals

This PR introduces a step-by-step guide to achieve the following:

• Service Creation: Set up a GraphQL service with a dedicated base path and listener.
• Logic Implementation: Use the Resource Design view to implement in-memory storage and shifting logic for news items.
• Real-time Streaming: Implement a NewsGenerator class to manage the stream iteration protocol required for subscriptions.
• Integrated Testing: Provide a clear workflow for testing Queries, Mutations, and Subscriptions using the built-in GraphiQL tool.

Summary by CodeRabbit

• Documentation
  • Added a comprehensive tutorial for a real-time GraphQL News Broadcasting Service, with end-to-end setup, step‑by‑step instructions, interactive run/test scenarios, and examples for queries, mutations, and subscriptions.
  • Updated site navigation to include the new GraphQL integration use-case guide in the documentation.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Walkthrough

Adds a new tutorial documenting a GraphQL News Broadcasting Service: workspace setup, artifacts (GraphQL schema, data types, custom NewsGenerator service), queries/mutations/subscriptions, in-memory persistence and streaming subscription workflow, plus end-to-end run and test instructions.

Changes

Cohort / File(s)	Change Summary
Documentation en/docs/integration-guides/usecases/graphql-news-broadcasting-service/graphql-news-broadcasting-service.md	New comprehensive tutorial for a real-time GraphQL News Broadcasting Service covering setup, artifact creation, schema and operation definitions (queries, mutations, subscriptions), service class implementation, streaming subscription wiring, and testing steps
Navigation en/mkdocs.yml	Added navigation entry under Use Cases linking to the new GraphQL News Broadcasting Service tutorial

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

🐰 I hop through docs with nimble cheer,
A streaming tale of news draws near,
Queries, subs, and mutating light—
I nibble bugs and make it right,
Hooray for broadcasts, crisp and clear! 🎉📡

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The description covers Purpose and Goals but is missing several required template sections including User stories, Release note, Documentation, Training, Certification, Marketing, Automation tests, Security checks, Samples, and other sections.	Complete the PR description by filling in all required template sections, particularly User stories, Release note, Documentation links, and Security checks sections.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarizes the main change - adding a comprehensive GraphQL News Broadcasting use case example to the documentation.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 2

🤖 Fix all issues with AI agents

In
`@en/docs/integration-guides/usecases/graphql-news-broadcasting-service/graphql-news-broadcasting-service.md`:
- Around line 318-323: The snippet's field declaration should be changed to
match the guidance: in class NewsGenerator replace the mutable field declaration
`private News[] newsItems;` with `private final News[] newsItems;` so the field
is immutable after construction; ensure the existing isolated init(News[]
newsItems) still assigns the cloned array to this.newsItems (using
newsItems.clone()) and leave the init method and class name (NewsGenerator,
init, newsItems) unchanged aside from the modifier update.
- Around line 321-323: The subscription init function currently clones the
newsItems snapshot, causing subscribers to miss future publishes; update init
(and any subscription setup) to retain a reference to the shared newsStorage (or
store a cursor/index into newsStorage) instead of calling newsItems.clone(), and
remove the behavior that immediately closes the stream when the referenced array
is empty—instead open the stream and deliver new items as they are appended by
publishNews (or iterate from the stored cursor through newsStorage so new
entries become visible to the subscriber). Ensure references to init,
publishNews, newsStorage, and newsItems are updated consistently so
subscriptions observe subsequent publishes.

🧹 Nitpick comments (1)

en/docs/integration-guides/usecases/graphql-news-broadcasting-service/graphql-news-broadcasting-service.md (1)

219-226: Reduce repeated “In the …” sentence starts for readability.

These sections have three consecutive sentences starting with “In the …”. Consider rephrasing one or two sentences to improve flow.

Also applies to: 345-350

[coderabbitai]

⚠️ Potential issue | 🟠 Major

🧩 Analysis chain

🏁 Script executed:

# First, find the file
find . -name "*graphql-news-broadcasting-service.md" -type f

Repository: wso2/docs-bi

Length of output: 164

---

🏁 Script executed:

# Read the file and examine the relevant sections
wc -l ./en/docs/integration-guides/usecases/graphql-news-broadcasting-service/graphql-news-broadcasting-service.md

Repository: wso2/docs-bi

Length of output: 168

---

🏁 Script executed:

# Read the init function section (lines 321-323)
sed -n '315,330p' ./en/docs/integration-guides/usecases/graphql-news-broadcasting-service/graphql-news-broadcasting-service.md

Repository: wso2/docs-bi

Length of output: 521

---

🏁 Script executed:

# Read the next() implementation section (lines 349-359)
sed -n '340,370p' ./en/docs/integration-guides/usecases/graphql-news-broadcasting-service/graphql-news-broadcasting-service.md

Repository: wso2/docs-bi

Length of output: 1483

---

🏁 Script executed:

# Read Step 12 and the complete next() implementation (lines 370-395)
sed -n '365,410p' ./en/docs/integration-guides/usecases/graphql-news-broadcasting-service/graphql-news-broadcasting-service.md

Repository: wso2/docs-bi

Length of output: 2026

---

🏁 Script executed:

# Read Step 15 and the publishNews expectations (lines 455-498)
sed -n '450,498p' ./en/docs/integration-guides/usecases/graphql-news-broadcasting-service/graphql-news-broadcasting-service.md

Repository: wso2/docs-bi

Length of output: 1906

---

🏁 Script executed:

# Let me examine the actual implementation steps more carefully
# to understand the complete flow described in the tutorial
sed -n '380,450p' ./en/docs/integration-guides/usecases/graphql-news-broadcasting-service/graphql-news-broadcasting-service.md

Repository: wso2/docs-bi

Length of output: 3336

---

🏁 Script executed:

# Check for the publishNews mutation implementation
sed -n '200,320p' ./en/docs/integration-guides/usecases/graphql-news-broadcasting-service/graphql-news-broadcasting-service.md

Repository: wso2/docs-bi

Length of output: 5090

---

Subscription stream won't receive newly published items due to array cloning.

The init function clones the newsItems array (Step 10, Line 322), which creates an isolated snapshot for each subscription. However, publishNews mutation adds items to the shared global newsStorage (Step 8). As a result, new mutations published after a subscription starts will not be visible to that subscriber's cloned copy. Additionally, if the array is empty at subscribe time, the stream returns () immediately (Step 11), ending it before any items can arrive. This contradicts Step 15's expectation that active subscriptions automatically receive broadcast updates.

To fix this, avoid cloning the array; instead, pass a reference to the shared storage or use a cursor-based approach to track the subscriber's read position while allowing new items to be visible to all active subscriptions.

🤖 Prompt for AI Agents

In
`@en/docs/integration-guides/usecases/graphql-news-broadcasting-service/graphql-news-broadcasting-service.md`
around lines 321 - 323, The subscription init function currently clones the
newsItems snapshot, causing subscribers to miss future publishes; update init
(and any subscription setup) to retain a reference to the shared newsStorage (or
store a cursor/index into newsStorage) instead of calling newsItems.clone(), and
remove the behavior that immediately closes the stream when the referenced array
is empty—instead open the stream and deliver new items as they are appended by
publishNews (or iterate from the stored cursor through newsStorage so new
entries become visible to the subscriber). Ensure references to init,
publishNews, newsStorage, and newsItems are updated consistently so
subscriptions observe subsequent publishes.