Initial Commit

README.md

@@ -0,0 +1,19 @@
+# BTClashWrapper
+
+`BTClashWrapper` is a java implementation of v1 the Clash of Clans REST API found at [https://developer.clashofclans.com/#/documentation](https://developer.clashofclans.com/#/documentation).
+
+### Usage
+
+Download the latest jar jar at [https://github.com/btilm305/BTClashWrapper/releases](https://github.com/btilm305/BTClashWrapper/releases) and include it in your project.
+
+	    public static void main(String[] args) {
+            ClashAPI clashAPI = BTClashWrapper.getAPIInstance(API_TOKEN);
+            // use ClashAPI here
+        }
+
+To use the API, first generate a [`ClashAPI`](btilm305.github.io/BTClashWrapper/com/btilm305/clashapi/ClashAPI.html]) object using your API token as seen in the above example. This class allows you to
+use all of the API features without having to worry about making HTTP requests on your own.
+
+### Documentation
+
+Documentation for the API can be found at [http://btilm305.github.io/BTClashWrapper/index.html](http://btilm305.github.io/BTClashWrapper/index.html).

pom.xml

@@ -0,0 +1,44 @@
+<?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">
+    <modelVersion>4.0.0</modelVersion>
+
+    <groupId>com.btilm305.clashapi</groupId>
+    <artifactId>BTClashWrapper</artifactId>
+    <version>1.0.0</version>
+
+    <dependencies>
+        <dependency>
+            <groupId>org.json</groupId>
+            <artifactId>json</artifactId>
+            <version>20140107</version>
+        </dependency>
+    </dependencies>
+
+    <build>
+        <defaultGoal>clean install</defaultGoal>
+        <plugins>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-shade-plugin</artifactId>
+                <version>2.3</version>
+                <executions>
+                    <execution>
+                        <phase>package</phase>
+                        <goals>
+                            <goal>shade</goal>
+                        </goals>
+                        <configuration>
+                            <artifactSet>
+                                <includes>
+                                    <include>org.json:json</include>
+                                </includes>
+                            </artifactSet>
+                        </configuration>
+                    </execution>
+                </executions>
+            </plugin>
+        </plugins>
+    </build>
+</project>

src/main/java/com/btilm305/clashapi/AbbreviatedClan.java

@@ -0,0 +1,65 @@
+package com.btilm305.clashapi;
+
+/**
+ * A representation of a clan containing data returned by most API calls. Includes most of the information about a clan.
+ * <p/>
+ * <p>More information about a clan can be requested with {@link ClashAPI#requestClan(ClanData)}</p>
+ */
+public interface AbbreviatedClan extends ClanData {
+
+    /**
+     * Returns the level of a clan
+     *
+     * @return the level of a clan, also known as clan XP level
+     */
+    int getClanLevel();
+
+    /**
+     * Returns the number of points that a clan has
+     *
+     * @return the number of clan points, determined using a weighed sum. Also known as the "clan trophy level"
+     */
+    int getClanPoints();
+
+    /**
+     * Returns the location of the clan
+     *
+     * @return the location of the clan
+     */
+    ClanLocation getLocation();
+
+    /**
+     * Returns the number of members that a clan has
+     *
+     * @return the number of members that a clan has
+     */
+    int getNumberOfMembers();
+
+    /**
+     * Returns the number of trophies required in order to join a clan
+     *
+     * @return the number of trophies required in order to join a clan
+     */
+    int getRequiredTrophies();
+
+    /**
+     * Returns the status of the clan
+     *
+     * @return the status of the clan, also known as "openness" (invite, open, closed)
+     */
+    ClanStatus getStatus();
+
+    /**
+     * Returns the war frequency of the clan
+     *
+     * @return the war frequency of the clan
+     */
+    ClanWarFrequency getWarFrequency();
+
+    /**
+     * Returns the number of war wins that the clan has
+     *
+     * @return the number of war wins that the clan has
+     */
+    int getWarWins();
+}

src/main/java/com/btilm305/clashapi/BTClashWrapper.java

@@ -0,0 +1,19 @@
+package com.btilm305.clashapi;
+
+import com.btilm305.clashapi.impl.ClashAPIImpl;
+
+/**
+ * API Factory class. This class should be accessed to create an instance of ClashAPI with your API token.
+ */
+public class BTClashWrapper {
+
+    /**
+     * Creates a ClashAPI instance with the provided API token
+     *
+     * @param apiToken the api token
+     * @return an API instance
+     */
+    public static ClashAPI getAPIInstance(String apiToken) {
+        return new ClashAPIImpl(apiToken);
+    }
+}

src/main/java/com/btilm305/clashapi/Clan.java

@@ -0,0 +1,23 @@
+package com.btilm305.clashapi;
+
+import java.util.List;
+
+/**
+ * A representation of all possible clan data provided by the API.
+ */
+public interface Clan extends AbbreviatedClan {
+
+    /**
+     * Returns the clan description
+     *
+     * @return the clan description
+     */
+    String getDescription();
+
+    /**
+     * Returns a list of members in the clan
+     *
+     * @return the list of clan members
+     */
+    List<ClanMember> getMembers();
+}

src/main/java/com/btilm305/clashapi/ClanData.java

@@ -0,0 +1,31 @@
+package com.btilm305.clashapi;
+
+/**
+ * The simplest representation of a Clan, containing only a few data fields. All API calls that return clan data contain
+ * at least this amount of information.
+ *
+ * <p>More information about a clan can be requested with {@link ClashAPI#requestClan(ClanData)}</p>
+ */
+public interface ClanData {
+
+    /**
+     * Returns the URLs for the clan badge images
+     *
+     * @return the URLs for the clan badge images
+     */
+    IconSet getBadgeIcons();
+
+    /**
+     * Returns the name of the clan
+     *
+     * @return the name of the clan
+     */
+    String getName();
+
+    /**
+     * Returns the clan tag
+     *
+     * @return the clan tag, starting with #
+     */
+    String getTag();
+}

src/main/java/com/btilm305/clashapi/ClanLocation.java

@@ -0,0 +1,33 @@
+package com.btilm305.clashapi;
+
+/**
+ * A representation of a location used in game. API calls for leaderboard information require a location as a parameter.
+ * If the location is not a country, {@code getCountryCode()} will return {@code null}
+ */
+public interface ClanLocation {
+
+    /**
+     * Returns the country code of a location
+     *
+     * @return the country code, or {@code null} if the location is not a country
+     */
+    String getCountryCode();
+
+    /**
+     * Returns the id of the location
+     * @return the id of the location
+     */
+    int getId();
+
+    /**
+     * Returns the name of the location
+     * @return the name of the location
+     */
+    String getName();
+
+    /**
+     * Returns whether the location is a country
+     * @return {@code true} if the location is a country, {@code false} otherwise
+     */
+    boolean isCountry();
+}

src/main/java/com/btilm305/clashapi/ClanMember.java

@@ -0,0 +1,43 @@
+package com.btilm305.clashapi;
+
+/**
+ * A representation of the data of clan members.
+ */
+public interface ClanMember extends Player {
+
+    /**
+     * Returns the player's rank in the clan (higher # of trophies = higher rank)
+     *
+     * @return the player's rank in the clan
+     */
+    int getClanRank();
+
+    /**
+     * Returns the number of troops the player has donated during the current season
+     *
+     * @return the number of troops the player has donated during the current season
+     */
+    int getNumberOfTroopsDonated();
+
+    /**
+     * Returns the number of troops the player has received from clan members during the current season
+     *
+     * @return the number of troops the player has received from clan members during the current season
+     */
+    int getNumberOfTroopsReceived();
+
+    /**
+     * Returns the player's previous rank in the clan. This is used to determine how far a player has
+     * risen or fallen in the clan's player ranks
+     *
+     * @return the player's previous rank in the clan
+     */
+    int getPreviousClanRank();
+
+    /**
+     * Returns the leadership role of the player
+     *
+     * @return the leadership role of the player
+     */
+    ClanMemberRole getRole();
+}

src/main/java/com/btilm305/clashapi/ClanMemberRole.java

@@ -0,0 +1,32 @@
+package com.btilm305.clashapi;
+
+/**
+ * An enum representing the possible leadership roles that clan members can have
+ */
+public enum ClanMemberRole {
+
+    LEADER("leader"),
+    CO_LEADER("coLeader"),
+    ELDER("admin"),
+    MEMBER("member");
+
+    private String id;
+
+    ClanMemberRole(String id) {
+        this.id = id;
+    }
+
+    public static ClanMemberRole fromId(String id) {
+        for (ClanMemberRole role : values()) {
+            if (role.id.equals(id)) {
+                return role;
+            }
+        }
+        return null;
+    }
+
+    @Override
+    public String toString() {
+        return id;
+    }
+}