Atlas Redis API

JavaDoc 1.0.3

Used by Atlas Network. Simple but blazingly fast all-purpose Redis API. Perfect for use in JSP, Minecraft, Server Backends or just about anything else!

Table of contents

• Getting started
• Connecting to Redis Server
• Subscribing to a channel
• Sending messages to a specific server
• Publishing messages
• Events & incoming messages
• License

Getting started

This API is intended for stand-alone usage, meaning that you do not need to run any extra spigot-plugins to use this library.

Add AtlasRedisAPI to your project

First, you need to setup the dependency on the AtlasRedisAPI. Replace VERSION with the version of the release.

Maven

<repositories>
    <repository>
        <id>jitpack.io</id>
        <url>https://jitpack.io</url>
    </repository>
</repositories>

<dependencies>
    <dependency>
        <groupId>com.github.Swofty-Developments</groupId>
        <artifactId>AtlasRedisAPI</artifactId>
        <version>VERSION</version>
    </dependency>
</dependencies>

Gradle

allprojects {
    repositories {
        ...
        maven { url 'https://jitpack.io' }
    }
}

dependencies {
    implementation 'com.github.Swofty-Developments:AtlasRedisAPI:VERSION'
}

Connecting to Redis Server

Before doing anything on the API, it is necessary to generate an instance of the RedisAPI class to connect to your Redis server.

// 
// The standard way of connecting to an instance
// Pass through a redis uri, must follow valid redis schema
// Inside of the URI, you are able to pass through the IP, PORT, USERNAME and PASSWORD
//
RedisAPI.generateInstance("redis://localhost:6379");

Subscribing to a channel

To receive data from your Redis server, you need to subscribe selected channels. You can do it simply just by calling:

//
// Note that you can register one class to more than one channel name, making it so that one listener class handles multiple channels.
//
RedisAPI.getInstance().registerChannel(
    "cove", // This is the name of the channel
    ExampleListener.class // Your listener class, see more about listening to Redis messages below.
);

// You can also use consumers to do the same task
RedisAPI.getInstance().registerChannel(
    "cove", // This is the name of the channel
    (event) -> { // the name of the variable for the Event
        System.out.println("message: " + event.getMessage() + " channel: " + event.getChannel());
    }
);

Sending messages to a specific server

Due to the nature of this API - There are probably going to be situations in which you will probably want to send a message to a specific pool listening to a channel. To do this, you need to add a Filter ID to your RedisAPI instance, this Filter ID is then checked against whenever you send a message from a different connection, check 'Publishing Messages' for more information on how to do that.

RedisAPI.getInstance().setFilterID("bungee"); // This RedisAPI instance will now block out any messages that do not have this filter id passed through with it.

Publishing messages

You can easily publish messages to the RedisAPI instance. It is not required to subscribe channel before you publish a message:

// For sending a message to every single instance of the Redis pool listening to the channel
RedisAPI.getInstance().publishMessage(
    ChannelRegistry.getFromName("cove"), // The name that you pass through here is the same as the name you pass through when registering a channel, look at 'Subscribing to a channel' for more information
    "examplemessage" // The message that you want to pass through the channel
);

// For sending a message to a specific instance of the Redis pool listening to a channel
RedisAPI.getInstance().publishMessage(
    "bungeecordserver", // This is the filter ID for the message, meaning that only Redis pools that have their filter code set to this value will recieve the message
    ChannelRegistry.getFromName("cove"), // The name that you pass through here is the same as the name you pass through when registering a channel, look at 'Subscribing to a channel' for more information
    "examplemessage" // The message that you want to pass through the channel
);

Events & Incoming messages

AtlasRedisAPI uses a class-based listener system, with every class being its own independant channel handler. Details are below:

//
// Only messages that are passed through the channel name given when registering the channel class will be passed onto this event.
// So if this class is registered using RedisAPI.getInstance().registerChannel("cove", ExampleListener.class) then this class will only listen to messages coming through the "cove" channel.
//
public class ExampleListener implements RedisMessagingReceiveInterface {
    @Override
    public void onMessage(String channel, String message) {
        System.out.println("test");
    }
}

License

AtlasRedisAPI is licensed under the permissive MIT license. Please see LICENSE.txt for more information.