andregasser/bigbone

BigBone - A Mastodon Client Library for Java and Kotlin

BigBone

BigBone is a Mastodon client library for Java and Kotlin.

Table of Contents

• Why BigBone
• Project Team
• Core Functionality
• Implementation Status
• Versioning
• Adding BigBone to Your Project
• Using BigBone
• Support
• Security
• Troubleshooting
• BigBone Contributors
• Contribution
• Projects Using BigBone
• Previous Work
• License

Why BigBone

BigBone is a fork of Mastodon4J, a Mastodon client library for Java and Kotlin that was published by Toshihiro Yagi. The goal of Mastodon4J was to provide an easy-to-use library for interacting with the Mastodon social media network from Java and Kotlin code. Unfortunately, it became abandoned and has not seen any updates since 2018.

Since Elon Musk's Twitter acquisition in 2022, Mastodon has gained tremendous popularity. A project that is so well received by the community deserves to have up-to-date and maintained client libraries. Because of this, we brought the Mastodon4J project back to life in November 2022. That's when this project, the BigBone client library for Java and the BigBone client library for Java and Kotlin, was born.

The name BigBone mostly has symbolic character. We opted for it as a nod to the awe-inspiring Mastodons of the Pleistocene era, characterised by their robust and colossal bones. We envision this library serving as a foundational skeleton for your Mastodon-related projects. Fun fact: There’s also Big Bone Lick State Park in Kentucky, a site where American Mastodons were excavated. May the BigBone library be as enduring and impactful as its namesake, providing strength and structure to your Mastodon endeavours.

Project Team

The project is currently taken care of by the following people:

• André Gasser
• Andreas Bartels
• Patrick Geselbracht

A big "Thank you" to everyone for the time they invest in this project. Without your help we would not be where we are right now.

Core Functionality

With a library like BigBone, you can build tools that allow you to

• act on statuses on your timelines (home, local, federated).
• post new statuses or edit existing ones (including media uploads)
• favourite and bookmark statuses
• manage lists
• post polls or vote on them
• schedule statuses
• send direct messages to other people
• manage filters
• follow/unfollow hashtags
• administer your Mastodon instance
• plus lots of other stuff!

Implementation Status

We did not release an official version on Maven Central yet, but there's a 2.0.0-SNAPSHOT which you can use to play around / experiment with. Just please be aware that with every new snapshot version, there can be breaking changes along the lines. There will be "darker places" in the library, where stuff will not work as expected. If you find issues, please file an issue.

BigBone does not yet implement the full API of Mastodon. Actually, there is still a lot to do. For details on the current API coverage please check out our API Coverage page.

Versioning

BigBone uses Semantic Versioning 2.0.0.

Adding BigBone to Your Project

Structure

BigBone consists of two main modules:

1. bigbone which exposes the Mastodon API endpoints as handy methods usable via a MastodonClient
2. bigbone-rx which adds a thin RxJava3 layer around the bigbone module

bigbone-rx for RxJava3

To find out more about the RxJava3 module—especially about default error handling—, please check the bigbone-rx README.

Gradle (Groovy DSL)

Instructions for adding BigBone 2.0.0-SNAPSHOT to your Gradle project (using Groovy DSL):

Repository:

repositories {
    maven {
        url "https://s01.oss.sonatype.org/content/repositories/snapshots/"
    }
}

Dependencies:

dependencies {
    implementation "social.bigbone:bigbone:2.0.0-SNAPSHOT"
    // Optional, if you want to use the BigBone RxJava3 wrappers
    implementation "social.bigbone:bigbone-rx:2.0.0-SNAPSHOT"
}

Gradle (Kotlin DSL)

Instructions for adding BigBone 2.0.0-SNAPSHOT to your Gradle project (using Kotlin DSL):

Repository:

repositories {
    maven {
        url = uri("https://s01.oss.sonatype.org/content/repositories/snapshots/")
    }
}

Dependencies:

dependencies {
    implementation("social.bigbone:bigbone:2.0.0-SNAPSHOT")
    // Optional, if you want to use the BigBone RxJava3 wrappers
    implementation("social.bigbone:bigbone-rx:2.0.0-SNAPSHOT")
}

Maven

Instructions for adding BigBone 2.0.0-SNAPSHOT to your Maven project:

Repository:

<repositories>
    <repository>
        <id>maven-central-snapshots</id>
        <name>Maven Central Snapshot Repository</name>
        <url>https://s01.oss.sonatype.org/content/repositories/snapshots/</url>
        <releases>
            <enabled>false</enabled>
        </releases>
        <snapshots>
            <enabled>true</enabled>
        </snapshots>
    </repository>
</repositories>

Dependencies:

<dependency>
    <groupId>social.bigbone</groupId>
    <artifactId>bigbone</artifactId>
    <version>2.0.0-SNAPSHOT</version>
</dependency>

        <!-- Optional, if you want to use the BigBone RxJava3 wrappers -->
<dependency>
    <groupId>social.bigbone</groupId>
    <artifactId>bigbone-rx</artifactId>
    <version>2.0.0-SNAPSHOT</version>
</dependency>

Using BigBone

For an easy introduction to using the library, we recommended that you take a look at the sample-* modules of this project. These modules provide examples for Java and Kotlin:

• sample-java for Java example code
• sample-kotlin for Kotlin example code

You can run them on your machine. Usually, they require some program arguments to be set before launch. Please have a look at the code for details.

We also provide some guidance in USAGE.md.

Support

Please check out SUPPORT.md for our preferred ways of supporting you.

Security

Please check out SECURITY.md for more details on how we handle security issues.

Troubleshooting

In this section we describe problems that have been reported to us by users of the library. Please read this section before you start working with it, as the tips given in this section might save you some time.

Request Not Sent / No Data Returned

Make sure you call .execute() on the BigBone library method you want to use. Here's an example:

val client = MastodonClient.Builder(instance).build()
val statuses = client.timelines.getTagTimeline(hashtag, TimelineMethods.StatusOrigin.LOCAL_AND_REMOTE).execute()

The same applies if you're using BigBone in a Java project.

Android Studio: BigBone Classes Not Found

An Android Studio user reported, that he was not able to use BigBone library in Android Studio, as classes were not recognized by the IDE (marked red instead). In this particular case, the fix was to switch/update to Android Studio Giraffe. See this issue for more details: #280

BigBone Contributors

The following people have actively contributed to the development of BigBone:

• Andreas - For actively contributing to the whole library project - thanks!
• Cédric Champeau - For putting the Gradle build scripts in great shape again

Contribution

Contributions are welcome! There's always something to be done and we try to keep an up-to-date list of issues that can be worked on. Please have a look at our Code Contribution Guidelines for more details.

Projects Using BigBone

Below we would like to mention projects that use the BigBone library.

• Apus: A social wall for conferences and other events created by McPringle. It can display the conference agenda from various sources together with Mastodon posts containing a configurable hashtag. Its purpose is to be displayed at the event on projector and TVs to show the attendees the next sessions and to boost posting on Mastodon.
• MastodonContentMover: MastodonContentMover is a command-line tool created by Tokyo Outsider that downloads your posts from one Mastodon instance, saving them as a set of files on your computer, and then re-posts them on any other Mastodon instance. Its purpose is to allow Mastodon users to move content they value when migrating from one instance to another, which is not currently possible within Mastodon itself.

Do you have a project that you would like to have listed here? Then please contact us.

Previous Work

Our personal thanks goes to Toshihiro and his contributors back then for building Mastodon4J. The library they have built in the past serves as a basis for our own development efforts. ❤️ Thank you! ❤️

License

BigBone is published under the MIT license. For more information on rights and obligations related to the MIT license, we would like to refer to this page here. The license file can be found in the LICENSE file.