Java RELP Library (rlp_01)

rlp_01 implements RELP protocol in Java using NIO interface and enables users to send syslog formatted messages to a RELP server such as rsyslog.

License

Apache License Version 2.0

Features

Current

• RELP Client

• RELP TLS

• RELP Server (See https://github.com/teragrep/rlp_03)

Example

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <dependencies>
        <!-- this library -->
        <dependency>
            <groupId>com.teragrep</groupId>
            <artifactId>rlp_01</artifactId>
            <version></version> <!-- see github -->
        </dependency>
        <!-- for syslog rfc5424 formatting -->
        <dependency>
            <groupId>com.cloudbees</groupId>
            <artifactId>syslog-java-client</artifactId>
            <version>1.1.7</version>
        </dependency>
    </dependencies>
</project>

import com.teragrep.rlp_01.RelpBatch;
import com.teragrep.rlp_01.RelpConnection;

import java.io.IOException;
import java.nio.charset.StandardCharsets;
import java.security.AlgorithmConstraints;
import java.security.GeneralSecurityException;
import java.util.Date;
import java.util.concurrent.TimeoutException;
import java.util.function.Supplier;

import com.cloudbees.syslog.Facility;
import com.cloudbees.syslog.Severity;
import com.cloudbees.syslog.SyslogMessage;

import javax.net.ssl.SSLContext;
import javax.net.ssl.SSLEngine;
import javax.net.ssl.SSLParameters;

class Main {

    public static void main(String[] args) {

        final String serverHostname = "127.0.0.1";
        final int serverPort = 601;

        boolean useTls = false;

        RelpConnection relpConnection;
        if (useTls) {
            try {
                SSLContext sslContext = SSLContextFactory.authenticatedContext(
                        "keystore.jks",
                        "changeit",
                        "TLSv1.3"
                );

                Supplier<SSLEngine> sslEngineSupplier = sslContext::createSSLEngine;
                /*
                // in case there is a need to configure these:
                SSLEngine sslEngine = sslContext.createSSLEngine();
                SSLParameters sslParameters = new SSLParameters();
                sslParameters.setAlgorithmConstraints();
                sslParameters.setCipherSuites();
                sslEngine.setSSLParameters(sslParameters);
                 */

                relpConnection = new RelpConnection(sslEngineSupplier);
            } catch (GeneralSecurityException | IOException exception) {
                exception.printStackTrace();
            }
        } else {
            relpConnection = new RelpConnection();
        }

        Main.openConnection(relpConnection, serverHostname, serverPort); // connection helper method

        RelpBatch relpBatch = new RelpBatch(); // create new relpBatch

        // Craft syslog message
        SyslogMessage syslog = new SyslogMessage()
                .withTimestamp(new Date().getTime())
                .withSeverity(Severity.WARNING)
                .withAppName("appName")
                .withHostname("hostName")
                .withFacility(Facility.USER)
                .withMsg("Hello RELP World!");


        relpBatch.insert(syslog.toRfc5424SyslogMessage().getBytes(StandardCharsets.UTF_8)); // insert one message

        boolean notSent = true;
        while (notSent) { // retry until sent

            try {
                relpConnection.commit(relpBatch); // send batch
            } catch (IOException | TimeoutException e) {
                e.printStackTrace();
            }

            if (!relpBatch.verifyTransactionAll()) { // failed batch
                relpBatch.retryAllFailed(); // re-queue failed events
                relpConnection.tearDown(); // teardown connection
                Main.openConnection(relpConnection, serverHostname, serverPort); // reconnect
            } else { // successful batch
                notSent = false;
            }
        }
    }

    private static void openConnection(RelpConnection relpConnection,
                                       String serverHostname,
                                       int serverPort) {
        // connect helper method
        boolean connected = false;
        while (!connected) {
            try {
                connected = relpConnection.connect(serverHostname, serverPort);  // connect
            } catch (IOException | TimeoutException e) { // error happened during the connect
                e.printStackTrace();
                relpConnection.tearDown(); // retry with clean connection
            }

            if (!connected) {
                // reconnect after an interval
                try {
                    Thread.sleep(500); // reconnect interval
                } catch (InterruptedException e) {
                    e.printStackTrace();
                }
            }
        }
    }
}

Debugging

Configure slf4j provider to enable debug messages. RelpParser logs only on trace level.

Contributing

You can involve yourself with our project by opening an issue or submitting a pull request.

Contribution requirements:

1. All changes must be accompanied by a new or changed test. If you think testing is not required in your pull request, include a sufficient explanation as why you think so.

2. Security checks must pass

3. Pull requests must align with the principles and values of extreme programming.

4. Pull requests must follow the principles of Object Thinking and Elegant Objects (EO).

Read more in our Contributing Guideline.

Contributor License Agreement

Contributors must sign Teragrep Contributor License Agreement before a pull request is accepted to organization’s repositories.

You need to submit the CLA only once. After submitting the CLA you can contribute to all Teragrep’s repositories.