From 7f5e8672cf3d64e304276f3aa49ebb0861aaa693 Mon Sep 17 00:00:00 2001 From: sk89q Date: Sun, 23 Mar 2014 16:28:04 -0700 Subject: [PATCH] Added Javadocs to various classes. --- .../java/com/skcraft/launcher/AssetsRoot.java | 34 ++++++++++++++++- .../com/skcraft/launcher/Configuration.java | 8 ++++ .../java/com/skcraft/launcher/Instance.java | 37 +++++++++++++++++++ .../com/skcraft/launcher/InstanceList.java | 33 +++++++++++++++++ .../skcraft/launcher/LauncherArguments.java | 3 ++ .../launcher/launch/JavaProcessBuilder.java | 5 +++ .../launcher/persistence/Persistence.java | 10 ++++- .../launcher/persistence/Scrambled.java | 27 ++++++++++++++ .../launcher/selfupdate/UpdateChecker.java | 4 ++ .../skcraft/launcher/update/BaseUpdater.java | 10 +++++ 10 files changed, 168 insertions(+), 3 deletions(-) diff --git a/src/main/java/com/skcraft/launcher/AssetsRoot.java b/src/main/java/com/skcraft/launcher/AssetsRoot.java index 16f7d16..11b94a1 100644 --- a/src/main/java/com/skcraft/launcher/AssetsRoot.java +++ b/src/main/java/com/skcraft/launcher/AssetsRoot.java @@ -23,25 +23,57 @@ import java.util.logging.Level; import static com.skcraft.launcher.util.SharedLocale._; +/** + * Represents a directory that stores assets for Minecraft. The class has + * various methods that abstract operations involving the assets (such + * as getting the path to a certain object). + */ @Log public class AssetsRoot { @Getter private final File dir; - public AssetsRoot(File dir) { + /** + * Create a new instance. + * + * @param dir the directory to the assets folder + */ + public AssetsRoot(@NonNull File dir) { this.dir = dir; } + /** + * Get the path to the index .json file for a version manfiest. + * + * @param versionManifest the version manifest + * @return the file, which may not exist + */ public File getIndexPath(VersionManifest versionManifest) { return new File(dir, "indexes/" + versionManifest.getAssetsIndex() + ".json"); } + /** + * Get the local path for a given asset. + * + * @param asset the asset + * @return the file, which may not exist + */ public File getObjectPath(Asset asset) { String hash = asset.getHash(); return new File(dir, "objects/" + hash.substring(0, 2) + "/" + hash); } + /** + * Create an instance of the assets tree builder, which copies the indexed + * assets (identified by hashes) into a directory where the assets + * have been renamed and moved to their real names and locations + * (i.e. sounds/whatever.ogg). + * + * @param versionManifest the version manifest + * @return the builder + * @throws LauncherException + */ public AssetsTreeBuilder createAssetsBuilder(@NonNull VersionManifest versionManifest) throws LauncherException { String indexId = versionManifest.getAssetsIndex(); File path = getIndexPath(versionManifest); diff --git a/src/main/java/com/skcraft/launcher/Configuration.java b/src/main/java/com/skcraft/launcher/Configuration.java index 0d08d66..8471e68 100644 --- a/src/main/java/com/skcraft/launcher/Configuration.java +++ b/src/main/java/com/skcraft/launcher/Configuration.java @@ -9,6 +9,14 @@ package com.skcraft.launcher; import com.fasterxml.jackson.annotation.JsonIgnoreProperties; import lombok.Data; +/** + * The configuration for the launcher. + *

+ * Default values are stored as field values. Note that if a default + * value is changed after the launcher has been deployed, it may not take effect + * for users who have already used the launcher because the old default + * values would have been written to disk. + */ @Data @JsonIgnoreProperties(ignoreUnknown = true) public class Configuration { diff --git a/src/main/java/com/skcraft/launcher/Instance.java b/src/main/java/com/skcraft/launcher/Instance.java index 490b04b..cc88c96 100644 --- a/src/main/java/com/skcraft/launcher/Instance.java +++ b/src/main/java/com/skcraft/launcher/Instance.java @@ -16,6 +16,10 @@ import java.io.File; import java.net.URL; import java.util.Date; +/** + * An instance is a profile that represents one particular installation + * of the game, with separate files and so on. + */ @Data public class Instance implements Comparable { @@ -34,31 +38,64 @@ public class Instance implements Comparable { @JsonIgnore private boolean selected; @JsonIgnore private boolean local; + /** + * Get the tile of the instance, which might be the same as the + * instance name if no title is set. + * + * @return a title + */ public String getTitle() { return title != null ? title : name; } + /** + * Update the given process builder with launch settings that are + * specific to this instance. + * + * @param builder the process builder + */ public void modify(JavaProcessBuilder builder) { if (launchModifier != null) { launchModifier.modify(builder); } } + /** + * Get the file for the directory where Minecraft's game files are + * stored, including user files (screenshots, etc.). + * + * @return the content directory, which may not exist + */ @JsonIgnore public File getContentDir() { return new File(dir, "minecraft"); } + /** + * Get the file for the package manifest. + * + * @return the manifest path, which may not exist + */ @JsonIgnore public File getManifestPath() { return new File(dir, "manifest.json"); } + /** + * Get the file for the Minecraft version manfiest file. + * + * @return the version path, which may not exist + */ @JsonIgnore public File getVersionPath() { return new File(dir, "version.json"); } + /** + * Get the file for the custom JAR file. + * + * @return the JAR file, which may not exist + */ @JsonIgnore public File getCustomJarPath() { return new File(getContentDir(), "custom_jar.jar"); diff --git a/src/main/java/com/skcraft/launcher/InstanceList.java b/src/main/java/com/skcraft/launcher/InstanceList.java index cc1ad27..69d53df 100644 --- a/src/main/java/com/skcraft/launcher/InstanceList.java +++ b/src/main/java/com/skcraft/launcher/InstanceList.java @@ -29,28 +29,58 @@ import java.util.concurrent.Callable; import static com.skcraft.launcher.LauncherUtils.concat; import static com.skcraft.launcher.util.SharedLocale._; +/** + * Stores the list of instances. + */ @Log public class InstanceList { private final Launcher launcher; @Getter private final List instances = new ArrayList(); + /** + * Create a new instance list. + * + * @param launcher the launcher + */ public InstanceList(@NonNull Launcher launcher) { this.launcher = launcher; } + /** + * Get the instance at a particular index. + * + * @param index the index + * @return the instance + */ public synchronized Instance get(int index) { return instances.get(index); } + /** + * Get the number of instances. + * + * @return the number of instances + */ public synchronized int size() { return instances.size(); } + /** + * Create a worker that loads the list of instances from disk and from + * the remote list of packages. + * + * @return the worker + */ public Enumerator createEnumerator() { return new Enumerator(); } + /** + * Get a list of selected instances. + * + * @return a list of instances + */ public synchronized List getSelected() { List selected = new ArrayList(); for (Instance instance : instances) { @@ -62,6 +92,9 @@ public class InstanceList { return selected; } + /** + * Sort the list of instances. + */ public synchronized void sort() { Collections.sort(instances); } diff --git a/src/main/java/com/skcraft/launcher/LauncherArguments.java b/src/main/java/com/skcraft/launcher/LauncherArguments.java index 967850c..2b340e0 100644 --- a/src/main/java/com/skcraft/launcher/LauncherArguments.java +++ b/src/main/java/com/skcraft/launcher/LauncherArguments.java @@ -11,6 +11,9 @@ import lombok.Data; import java.io.File; +/** + * The command line arguments that the launcher accepts. + */ @Data public class LauncherArguments { diff --git a/src/main/java/com/skcraft/launcher/launch/JavaProcessBuilder.java b/src/main/java/com/skcraft/launcher/launch/JavaProcessBuilder.java index c197ae7..726cdbf 100644 --- a/src/main/java/com/skcraft/launcher/launch/JavaProcessBuilder.java +++ b/src/main/java/com/skcraft/launcher/launch/JavaProcessBuilder.java @@ -17,6 +17,11 @@ import java.util.List; import java.util.regex.Matcher; import java.util.regex.Pattern; +/** + * A tool to build the entire command line used to launch a Java process. + * It combines flags, memory settings, arguments, the class path, and + * the main class. + */ @ToString public class JavaProcessBuilder { diff --git a/src/main/java/com/skcraft/launcher/persistence/Persistence.java b/src/main/java/com/skcraft/launcher/persistence/Persistence.java index 0eae3cc..c6580a8 100644 --- a/src/main/java/com/skcraft/launcher/persistence/Persistence.java +++ b/src/main/java/com/skcraft/launcher/persistence/Persistence.java @@ -19,8 +19,14 @@ import java.util.WeakHashMap; import java.util.logging.Level; /** - * Simple persistence framework that can bind an object to a file and later allow for - * code utilizing the object to save it globally. + * Simple persistence framework that can read an object from a file, bind + * that object to that file, and allow any code having a reference to the + * object make changes to the object and save those changes back to disk. + *

+ * For example: + * 
config = Persistence.load(file, Configuration.class);
+ * config.changeSomething();
+ * Persistence.commit(config);
*/ @Log public final class Persistence { diff --git a/src/main/java/com/skcraft/launcher/persistence/Scrambled.java b/src/main/java/com/skcraft/launcher/persistence/Scrambled.java index c96753c..672bbb0 100644 --- a/src/main/java/com/skcraft/launcher/persistence/Scrambled.java +++ b/src/main/java/com/skcraft/launcher/persistence/Scrambled.java @@ -11,10 +11,37 @@ import java.lang.annotation.Retention; import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; +/** + * Classes that are annotated with this will be saved scrambled + * to disk when saved using {@link com.skcraft.launcher.persistence.Persistence}. + *

+ * The data may be scrambled using an encryption algorithm, but it's not + * done with security in mind. Decryption requires a key, and that + * key would either have to be stored in the source code, defeating the + * purpose of encryption, or the user would have to be prompted with a + * password every time (possibly through an OS key ring service). + * That creates extra hassle, so it is not done here. + *

+ * Therefore , you should not depend on data that is scrambled to + * be secure. It does, however, make it impossible for most people + * to just read the file's contents, which is "better than nothing" + * Documentation should not indicate to the user that the data is + * protected however, because that would provide a false sense of + * security. + *

+ * Account data is scrambled to make it harder to extract passwords. + */ @Retention(RetentionPolicy.RUNTIME) @Target(ElementType.TYPE) public @interface Scrambled { + /** + * A key used in scrambling. + *

+ * The key should not change once deployed. + * + * @return a key + */ String value(); } diff --git a/src/main/java/com/skcraft/launcher/selfupdate/UpdateChecker.java b/src/main/java/com/skcraft/launcher/selfupdate/UpdateChecker.java index 439608a..f0e8517 100644 --- a/src/main/java/com/skcraft/launcher/selfupdate/UpdateChecker.java +++ b/src/main/java/com/skcraft/launcher/selfupdate/UpdateChecker.java @@ -17,6 +17,10 @@ import java.util.concurrent.Callable; import static com.skcraft.launcher.util.SharedLocale._; +/** + * A worker that checks for an update to the launcher. A URL is returned + * if there is an update to be downloaded. + */ @Log public class UpdateChecker implements Callable { diff --git a/src/main/java/com/skcraft/launcher/update/BaseUpdater.java b/src/main/java/com/skcraft/launcher/update/BaseUpdater.java index f189932..9fa52a8 100644 --- a/src/main/java/com/skcraft/launcher/update/BaseUpdater.java +++ b/src/main/java/com/skcraft/launcher/update/BaseUpdater.java @@ -39,6 +39,16 @@ import static com.skcraft.launcher.LauncherUtils.checkInterrupted; import static com.skcraft.launcher.LauncherUtils.concat; import static com.skcraft.launcher.util.SharedLocale._; +/** + * The base implementation of the various routines involved in downloading + * and updating Minecraft (including the launcher's modpacks), such as asset + * downloading, .jar downloading, and so on. + *

+ * Updating actually starts in {@link com.skcraft.launcher.update.Updater}, + * which is the update worker. This class exists to allow updaters that don't + * use the launcher's default modpack format to reuse these update + * routines. (It also makes the size of the Updater class smaller.) + */ @Log public abstract class BaseUpdater {