Skip to content

README.md

Latest commit

 

History

History
89 lines (59 loc) · 3.29 KB

README.md

File metadata and controls

89 lines (59 loc) · 3.29 KB
Raw

Caution

This project is in early development. APIs may change without notice — use at your own risk.

A Matrix Client SDK for Java

A client-side Java library for the Matrix protocol.

Purpose

This library aims to allow authors to build any kind of Matrix program such as a bot or a desktop client, the library handles all matters of serialization, validation and authentication.

Quick start

import io.github.hikingc.matrixsdk.api.MatrixAuth;
import io.github.hikingc.matrixsdk.api.MatrixClient;
import io.github.hikingc.matrixsdk.api.auth.TokenMetadata;
import io.github.hikingc.matrixsdk.context.DiscoveryResponse;

MatrixAuth auth = new MatrixAuth(URI.create("https://example.org")); // Set the URI of your Matrix server.
DiscoveryResponse response = auth.fetchWellKnown(); // Fetch well known for future operations

TokenMetadata token = auth.login(CLIENT_NAME, PORT, DEVICE_ID); // Set configuration parameters
// After doing the login with the server in your browser, you will be returned the tokens...
MatrixClient client = MatrixClient.create(response, token.accessToken()); // Use any service you want!

Feature support

Service Capabilities Status
Rooms Banning, kicking, room summary, room search Supported
Events Sending messages, reading room events, /sync Partial
User Data Profile search, profile modification Supported
Filtering Creating and retrieving filters Supported
Auth OpenIDConnect handshake Supported

Current project status

The baseline to reach v1.0 is to implement all endpoints that are required in the specification, this means:

  • Support for OAuth 2.0 and Legacy API Auth.
  • Be able to send and receive events seamlessly without handling raw JSON.
  • Get room and server information without losing any data field while deserializing.

Current limitations

  1. This project does not handle multimedia resources, it does expose the necessary Objects to handle serialization (RoomMessage) but consumers are required to bring their own library to pass required metadata.
  2. This project does not allow for the creation or hookup of custom event types, for example: org.custom.type. It does recognize these events with UnknownEvent.java but consumers will be required to cast to a proper Object type.
  3. Resource serialization/deserialization depends heavily on Jackson 3.0.

Installation

(None currently!)

Requirements

  • Java 23+

Testing

  • Tests use WireMock for HTTP stubbing and JUnit 5 as the test framework.
  • Each service component has its own test file; all tests must pass to ensure the library works as intended.

To run the test suite:

./mvnw test

Note

When using IntelliJ, JUnit might throw IllegalAccessError, fix this by either checking "Do not use --module-path option" or configuring Maven as the test runner.

Dependencies

  • Jackson required for JSON handling.
  • java-http required for creating a small server for callbacks.

License

See LICENSE