search

meraki-analytics / orianna

A Java framework for the Riot Games League of Legends API (http://developer.riotgames.com/).
MIT License
182 stars 56 forks source link
api java league-of-legends riot-games-api

readme

MIT Licensed Maven Central Documentation Status JavaDocs DOI

Orianna

A Java adaptation of the Riot Games League of Legends API (https://developer.riotgames.com/).

Orianna is the sister library to Cassiopeia (Python). It's been designed with usability in mind - making sure all the bookkeeping is done right so you can focus on getting the data you need and building your application.

Orianna is licensed under the MIT License.

Documentation & Examples

Detailed documentation about Orianna is located here. The full JavaDoc for Orianna is available here. Examples of using Orianna can be found here.

Features

Orianna is designed to make the lives of Riot API developers as easy as possible. Here are some of the ways we do it:

How to get it

Orianna is distributed through the releases page and through Maven Central. The easiest way to get it is by using Maven or Gradle.

Maven

To add the latest Orianna release version to your maven project, add the dependency to your pom.xml dependencies section:

<dependencies>
  <dependency>
    <groupId>com.merakianalytics.orianna</groupId>
    <artifactId>orianna</artifactId>
    <version>4.0.0-rc9</version>
    <!-- or, for Android: -->
    <artifactId>orianna-android</artifactId>
    <version>4.0.0-rc9</version>
  </dependency>
</dependencies>

Or, if you want to get the latest development version, add the Sonaype Snapshot Repository to your pom.xml as well:

<dependencies>
  <dependency>
    <groupId>com.merakianalytics.orianna</groupId>
    <artifactId>orianna</artifactId>
    <version>4.0.0-SNAPSHOT</version>
    <!-- or, for Android: -->
    <artifactId>orianna-android</artifactId>
    <version>4.0.0-SNAPSHOT</version>
  </dependency>
</dependencies>

<repositories>
  <repository>
    <id>snapshots-repo</id>
    <url>https://oss.sonatype.org/content/repositories/snapshots</url>
    <releases>
      <enabled>false</enabled>
    </releases>
    <snapshots>
      <enabled>true</enabled>
    </snapshots>
  </repository>
</repositories>

Gradle

To add the latest Orianna release version to your gradle project, add the Maven Central repository to your build.gradle repositories section, and add the dependency to your build.gradle dependencies section:

repositories {
  mavenCentral()
}

dependencies {
  implementation "com.merakianalytics.orianna:orianna:4.0.0-rc9"
  // or, for Android:
  implementation "com.merakianalytics.orianna:orianna-android:4.0.0-rc9"
}

Or, if you want to get the latest development version, add the Sonaype Snapshot Repository to your build.gradle instead:

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

dependencies {
  implementation "com.merakianalytics.orianna:orianna:4.0.0-SNAPSHOT"
  // or, for Android:
  implementation "com.merakianalytics.orianna:orianna-android:4.0.0-SNAPSHOT"
}

Using the release JAR directly

Grab the latest JAR from the releases page and add it to your project dependencies. JARs are provide both with and without Orianna's dependencies included. The jar-with-dependencies version will get you up & running faster, but can cause version conflicts if your project has other dependencies.

If you're using the JAR without dependencies inlcuded, Orianna depends on the following libraries which will also need to be added as dependencies:

Example

Check out a basic example of Orianna in action. More examples are available here.

import com.merakianalytics.orianna.Orianna;
import com.merakianalytics.orianna.types.common.Queue;
import com.merakianalytics.orianna.types.common.Region;
import com.merakianalytics.orianna.types.core.league.League;
import com.merakianalytics.orianna.types.core.staticdata.Champion;
import com.merakianalytics.orianna.types.core.staticdata.Champions;
import com.merakianalytics.orianna.types.core.summoner.Summoner;

public class Example {
    public static void main(String[] args) {
        Orianna.setRiotAPIKey("YOUR-API-KEY");
        Orianna.setDefaultRegion(Region.NORTH_AMERICA);

        Summoner summoner = Orianna.summonerNamed("FatalElement").get();
        System.out.println(summoner.getName() + " is level " + summoner.getLevel() + " on the " + summoner.getRegion() + " server.");

        Champions champions = Orianna.getChampions();
        Champion randomChampion = champions.get((int)(Math.random() * champions.size()));
        System.out.println("He enjoys playing champions such as " + randomChampion.getName());

        League challengerLeague = Orianna.challengerLeagueInQueue(Queue.RANKED_SOLO).get();
        Summoner bestNA = challengerLeague.get(0).getSummoner();
        System.out.println("He's not as good as " + bestNA.getName() + " at League, but probably a better Java programmer!");
    }
}

Configuring Orianna

Orianna ships with a default configuration designed to get new users going as quickly as possible. However, you may find you want to take advantage of some of the configuration options Orianna supports by replacing that configuration with your own.

Orianna is able to automatically load your Riot API Key from your environment variables on startup. To take advantage of this, set your RIOT_API_KEY environment variable to your Riot API Key.

For more complex configuration, just download the default configuration, make the changes you'd like, and load the new configuration file when your program starts. Documentation describing the full range of configuration options available with Orianna can be found here.

Orianna.loadConfiguration(new File("/path/to/your/configuration-file.json"));

Alternatively, Orianna can automatically load your configuration file on startup if you set your ORIANNA_CONFIGURATION_PATH environment variable to the path of your configuration file.

Android Usage Note

If you're using Orianna with Android, be aware that using the default configuration which uses the RiotAPI Data Source will result in leaking your API key to the users of your application as they can access the program memory and network requests Orianna is making. For personal applications you won't be sharing, that's okay. If you're going to distribute your application, however, you'll need to have Orianna make its calls indirectly through a proxy server. You can use Kernel to easily set up a proxy server along with the Kernel Data Source in Orianna to send your requests to it instead of the Riot API.

Simple Kernel Configuration

Here's an example of an Orianna configuration file that uses Kernel instead of the Riot API. Specifically, note this section which replaces this section from the default configuration.

Recommended Kernel Configuration

It's recommended to configure Kernel to send "data" layer Orianna objects, rather than the "dto" layer objects it sends by default which mirror the Riot API exactly. This will reduce the amount of repeated computation that needs to be done between the Kernel server and the client Orianna instance. To use the "data" layer, configure your Kernel instance to "produceCoreData", as shown here. On the Orianna end, you can then replace the Riot API configuration from the default configuration (shown here) with the "data" layer Kernel data source as shown here. You can also remove most of the transformers from the default configuration (shown here) as they won't be needed.

Questions & Contributions

Feel free to send pull requests or to contact us via GitHub or Discord. We also hang around the Riot API Discord, so come by and say hello. We love to hear what people are building with Orianna! If you would like to help us maintain Orianna, let us know on our Discord.

Bugs

If you find bugs please let us know via a pull request or issue.

Citing Orianna

If you used Orianna for your research, please cite the project.

Support Us

If you've loved using Orianna, consider supporting us through PayPal or Patreon.

Disclaimer

Orianna isn't endorsed by Riot Games and doesn't reflect the views or opinions of Riot Games or anyone officially involved in producing or managing League of Legends. League of Legends and Riot Games are trademarks or registered trademarks of Riot Games, Inc. League of Legends © Riot Games, Inc.