{"id":19901558,"url":"https://github.com/cettia/cettia-starter-kit","last_synced_at":"2025-05-02T23:31:53.763Z","repository":{"id":38960479,"uuid":"132007021","full_name":"cettia/cettia-starter-kit","owner":"cettia","description":"Get started with Cettia","archived":false,"fork":false,"pushed_at":"2023-01-03T20:34:54.000Z","size":2716,"stargazers_count":8,"open_issues_count":18,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-04-07T08:35:15.390Z","etag":null,"topics":["cettia","chat-application","comet","framework-agnostic","java","long-polling","real-time","streaming","websocket"],"latest_commit_sha":null,"homepage":"https://cettia.io/guides/getting-started/","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cettia.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-05-03T14:27:57.000Z","updated_at":"2022-10-15T04:48:49.000Z","dependencies_parsed_at":"2022-09-19T15:03:10.101Z","dependency_job_id":null,"html_url":"https://github.com/cettia/cettia-starter-kit","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cettia%2Fcettia-starter-kit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cettia%2Fcettia-starter-kit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cettia%2Fcettia-starter-kit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cettia%2Fcettia-starter-kit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cettia","download_url":"https://codeload.github.com/cettia/cettia-starter-kit/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252122276,"owners_count":21698305,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cettia","chat-application","comet","framework-agnostic","java","long-polling","real-time","streaming","websocket"],"created_at":"2024-11-12T20:15:31.221Z","updated_at":"2025-05-02T23:31:52.797Z","avatar_url":"https://github.com/cettia.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Getting Started\n\nThe easiest way to get started with Cettia is to play with the [Cettia Starter Kit](https://github.com/cettia/cettia-starter-kit) that is a basic chat application made with Cettia.\n\n![cettia-starter-kit-1555758896147](https://user-images.githubusercontent.com/1095042/56456590-5947a080-63a9-11e9-9155-36d49d33ed4c.gif)\n\n## Running the Starter Kit\n\nThe starter kit requires Java 8+. Clone or download the repository and run `./mvnw install`. If you have installed Maven 3+, you can do `mvn install`.\n\n```\ngit clone https://github.com/cettia/cettia-starter-kit.git\ncd cettia-starter-kit\n./mvnw install\n```\n\n### Server\n\nThe server example is located in the `example-server` project.\n\n- [`/example-server/pom.xml`](https://github.com/cettia/cettia-starter-kit/blob/master/example-server/pom.xml)\n- [`/example-server/src/main/java/io/cettia/starter/ExampleServerAction.java`](https://github.com/cettia/cettia-starter-kit/blob/master/example-server/src/main/java/io/cettia/starter/ExampleServerAction.java)\n\nTo run the example, you should integrate it with a web framework first. The starter kit provides example projects integrated with each web framework supporting Cettia as follows. Pick one according to your favorite framework, enter the project directory, and run the Maven command.\n\n| Web framework  | Maven project   | Maven command                    | pom.xml                                                                           | Main class                                                                                                                                                                  |\n|----------------|-----------------|----------------------------------|-----------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| Atmosphere     | atmosphere2     | `../mvnw jetty:run`                  | [pom.xml](https://github.com/cettia/cettia-starter-kit/blob/master/atmosphere2/pom.xml)     | [CettiaInitializer](https://github.com/cettia/cettia-starter-kit/blob/master/atmosphere2/src/main/java/io/cettia/starter/atmosphere2/CettiaInitializer.java)  |\n| Grizzly        | grizzly2        | `../mvnw clean package exec:java`    | [pom.xml](https://github.com/cettia/cettia-starter-kit/blob/master/grizzly2/pom.xml)        | [CettiaServer](https://github.com/cettia/cettia-starter-kit/blob/master/grizzly2/src/main/java/io/cettia/starter/grizzly2/CettiaServer.java)                  |\n| Java EE        | javaee7         | `../mvnw jetty:run`                  | [pom.xml](https://github.com/cettia/cettia-starter-kit/blob/master/javaee7/pom.xml)         | [CettiaInitializer](https://github.com/cettia/cettia-starter-kit/blob/master/javaee7/src/main/java/io/cettia/starter/javaee7/CettiaInitializer.java)          |\n| Netty          | netty4          | `../mvnw clean package exec:java`    | [pom.xml](https://github.com/cettia/cettia-starter-kit/blob/master/netty4/pom.xml)          | [CettiaServer](https://github.com/cettia/cettia-starter-kit/blob/master/netty4/src/main/java/io/cettia/starter/netty4/CettiaServer.java)                      |\n| Play framework | play2           | `sbt run` or `../mvnw play2:run`     | [build.sbt](https://github.com/cettia/cettia-starter-kit/blob/master/play2/build.sbt)       | [CettiaController](https://github.com/cettia/cettia-starter-kit/blob/master/play2/app/io/cettia/starter/play2/CettiaController.java)                          |\n| Spring WebFlux | spring-webflux5 | `../mvnw spring-boot:run`            | [pom.xml](https://github.com/cettia/cettia-starter-kit/blob/master/spring-webflux5/pom.xml) | [CettiaServer](https://github.com/cettia/cettia-starter-kit/blob/master/spring-webflux5/src/main/java/io/cettia/starter/spring5/CettiaServer.java)            |\n| Spring Web MVC | spring-webmvc4  | `../mvnw spring-boot:run`            | [pom.xml](https://github.com/cettia/cettia-starter-kit/blob/master/spring-webmvc4/pom.xml)  | [CettiaServer](https://github.com/cettia/cettia-starter-kit/blob/master/spring-webmvc4/src/main/java/io/cettia/starter/spring4/CettiaServer.java )            |\n| Vert.x         | vertx2          | `../mvnw clean package vertx:runMod` | [pom.xml](https://github.com/cettia/cettia-starter-kit/blob/master/vertx2/pom.xml)          | [CettiaServerVerticle](https://github.com/cettia/cettia-starter-kit/blob/master/vertx2/src/main/java/io/cettia/starter/vertx2/CettiaServerVerticle.java)      |\n|                | vertx3          | `../mvnw clean package exec:java`    | [pom.xml](https://github.com/cettia/cettia-starter-kit/blob/master/vertx3/pom.xml)          | [CettiaServerVerticle](https://github.com/cettia/cettia-starter-kit/blob/master/vertx3/src/main/java/io/cettia/starter/vertx3/CettiaServerVerticle.java)      |\n\nThen, it will run a server that listens on port 8080 and exposes an endpoint `/cettia`. For how to integrate Cettia with the framework of your choice, see the above projects' source code and the reference documentation's [Plugging Into the Web Framework](https://cettia.io/guides/cettia-tutorial/#plugging-into-the-web-framework) section.\n\n### Web\n\nThe browser-based client example is located in the `example-web` project.\n\n- [`/example-web/src/main/webapp/index.html`](https://github.com/cettia/cettia-starter-kit/blob/master/example-web/src/main/webapp/index.html)\n- [`/example-web/src/main/webapp/app.js`](https://github.com/cettia/cettia-starter-kit/blob/master/example-web/src/main/webapp/app.js)\n\nEnter the `example-web` Maven project, start a static web server as follows, and then visit `http://localhost:8070/`.\n\n```\ncd example-web\n../mvnw jetty:run -Djetty.port=8070\n```\n\n#### On the fly\n\nIf you prefer to run code snippets on the fly, open the developer tools on this page, click the console tab and then type `cettia` to the console.\n\n```\n\u003e cettia;\n\u003c {open: function, transport: Object, util: Object}\n```\n\nThen, you should see that the `cettia` object is available. For your information, every page of [https://cettia.io](https://cettia.io) loads the latest version of `cettia` object so that you can play with the `cettia` object at any time.\n\n### React Native\n\nThe React Native example is located in the `example-react-native` project.\n\n- [`/example-react-native/App.js`](https://github.com/cettia/cettia-starter-kit/blob/master/example-react-native/App.js)\n\nMake sure that you have set up the React Native development environment. Enter the `example-react-native` npm project, and type the following command.\n\n```\ncd example-react-native\nnpm install\n```\n\nThen, you can run the example with React Native CLI as follows.\n\n#### iOS\n\n```\nreact-native run-ios\n```\n\n#### Android\n\n```\nreact-native run-android\n```\n\n### Node.js\n\nThe Node.js example is located in the `example-node` project.\n\n- [`/example-node/main.js`](https://github.com/cettia/cettia-starter-kit/blob/master/example-node/main.js)\n\nYou need to have installed Node.js version 4 and above. Enter the `example-web` npm project, install the dependencies, and start main.js.\n\n```\ncd example-node\nnpm install\nnpm start\n```\n\n#### On the fly\n\nIf you prefer to run code snippets on the fly, open a Node.js console and copy the contents of the main.js and paste it into the console. You can deal with the `socket` directly.\n\n## Understanding the Example\n\nHere are the user stories implemented in the example.\n\n- As a guest I want to sign in to the application by entering a username only so that I don't have to go through an annoying sign-up process.\n- As a user I want to join the lounge channel automatically after sign in so that I can talk with everyone.\n- As a user I want to send messages to the lounge channel so that everyone can receive my messages.\n- As a user I want to receive messages when others send them to the lounge channel so that I can keep conversation in real-time.\n\nIn this guide we will skip explanation about view components and focus on how we can exchange events between the server and the client in real-time.\n\n### Opening a Socket\n\nAdd a `socket` event handler in the server side.\n\n```java\nserver.onsocket((ServerSocket socket) -\u003e {\n  System.out.println(socket + \" is created\");\n});\n```\n\nThen, in the client, open a socket side adding a `username` parameter to the query string of the URI.\n\n```javascript\nconst uri = `http://localhost:8080/cettia?username=${encodeURIComponent(username)}`;\nconst socket = cettia.open(uri);\n```\n\nFor convenience sake, in the rest of the guide, we will assume that a `socket` is already opened. For the details, see the reference documentation's [Opening a Socket](https://cettia.io/guides/cettia-tutorial/#opening-a-socket).\n\n### Tracking the Socket Lifecycle\n\nRegister the following built-in event handlers to track each side of socket.\n\nThe server-side:\n\n```java\nserver.onsocket((ServerSocket socket) -\u003e {\n  Action\u003cVoid\u003e logState = v -\u003e System.out.println(socket + \" transitions to \" + socket.state());\n  // If it performs the handshake successfully, or the connection is recovered by the client reconnection\n  socket.onopen(logState);\n  // If it fails to perform the handshake, or the connection is disconnected for some reason\n  socket.onclose(logState);\n  // After one minute has elapsed since disconnection\n  socket.ondelete(logState);\n});\n```\n\nThe client-side:\n\n```javascript\nconst addSystemMessage = text =\u003e addMessage({sender: \"system\", text});\nsocket.on(\"connecting\", () =\u003e addSystemMessage(\"The socket starts a connection.\"));\nsocket.on(\"open\", () =\u003e addSystemMessage(\"The socket establishes a connection.\"));\nsocket.on(\"close\", () =\u003e addSystemMessage(\"All transports failed to connect or the connection was disconnected.\"));\nsocket.on(\"waiting\", (delay) =\u003e addSystemMessage(`The socket will reconnect after ${delay} ms`));\n```\n\n`addMessage` is a function to add a message to the message list by manipulating the DOM. If you are in the console, declare the function instead, as follows.\n\n```javascript\nconst addMessage = ({sender, text}) =\u003e console.log(`${sender} sends ${text}`);\n```\n\nFor the details including state transition diagrams, see the reference documentation's [Socket Lifecycle](https://cettia.io/guides/cettia-tutorial/#socket-lifecycle).\n\n### Storing Information in a Socket\n\nA server-side socket can have custom properties in the form of a key-value pair and a set element.\n\n```java \nserver.onsocket((ServerSocket socket) -\u003e {\n  // Sets a username\n  socket.set(\"username\", findParam(socket.uri(), \"username\"));\n  // Joins the lounge channel where everyone gets together\n  socket.tag(\"channel:lounge\");\n});\n```\n\nSee the reference documentation's [Attributes and Tags](https://cettia.io/guides/cettia-tutorial/#attributes-and-tags) for the details.\n\n### Working with Sockets\n\nTo send an event to certain sockets in the server, write a socket predicate that selects which sockets to handle, and pass it to `find()`, and write a socket action that sends an event to the given socket, and pass it to `execute()`. The server will find sockets that matches the given predicate and execute the given action passing found sockets one by one.\n\n```java\nserver.onsocket((ServerSocket socket) -\u003e {\n  socket.on(\"message\", (Map\u003cString, Object\u003e input) -\u003e {\n    String text = (String) input.get(\"text\");\n\n    Map\u003cString, Object\u003e output = new LinkedHashMap\u003c\u003e();\n    output.put(\"sender\", socket.get(\"username\"));\n    output.put(\"text\", text);\n\n    System.out.println(socket.get(\"username\") + \"@\" + socket.id() + \" sends '\" + text + \"' to the lounge\");\n    server.find(s -\u003e s.tags().contains(\"channel:lounge\")).execute(s -\u003e s.send(\"message\", output));\n  });\n});\n```\n\nUnless you need to deal with a socket passed to a socket predicate and a socket action directly, you can rewrite the above code more concisely with predefined predicates and convenient methods as follows. \n\n```java\nserver.onsocket((ServerSocket socket) -\u003e {\n  socket.on(\"message\", (Map\u003cString, Object\u003e input) -\u003e {\n    // ...\n    // With 'import static io.cettia.ServerSocketPredicates.tag;'\n    server.find(tag(\"channel:lounge\")).send(\"message\", output);\n  });\n});\n```\n\nIn the client side, register a `message` event handler \n\n```javascript\nsocket.on(\"message\", message =\u003e addMessage(message));\n```\n\nAnd send a `message` event with with a message, `text`. You will see all sockets joined the lounge channel receive the message.\n\n```javascript\nsocket.send(\"message\", {text});\n```\n\nFor the details, See the reference documentation's [Working with Sockets](https://cettia.io/guides/cettia-tutorial/#working-with-sockets) and [Advanced Sockets Handling](https://cettia.io/guides/cettia-tutorial/#advanced-sockets-handling) sections.\n\n## Conclusion\n\nIn this guide, we walked through basic features of Cettia with the [Cettia Starter Kit](https://github.com/cettia/cettia-starter-kit); opening a socket, tracking the socket lifecycle, storing information in a socket, and working with sockets. To learn more about Cettia, including \n\n- How to run an application on your favorite web framework\n- What types are allowed for event data\n- How to use POJOs as event data\n- How to scale an application\n- How to recover missed events, and so on\n\nTake a look at the reference documentation – [Building Real-Time Web Applications With Cettia](https://cettia.io/guides/cettia-tutorial). If you have any questions, please let us know on the [Cettia Groups](http://groups.google.com/group/cettia).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcettia%2Fcettia-starter-kit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcettia%2Fcettia-starter-kit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcettia%2Fcettia-starter-kit/lists"}