Updater 2.3- Easy, Safe, and Policy-Compliant auto-updating for your plugins [NEW!]

Discussion in 'Resources' started by Gravity, Aug 28, 2012.

Thread Status:
Not open for further replies.
  1. Offline

    Gravity Retired Staff

    Updater - Version 2.3
    Updater is an easy-to-use but robust and fully policy-compliant plugin updating system. It provides plugin developers with the ability to both check for and download new updates straight from BukkitDev, and requires no web server setup to function.

    Download and Source:
    Updater is a single class file that you need to add to your plugin. Simply create a new class somewhere in your plugin named "Updater", and populate it with Updater's source code, which you can find by clicking the "Get Updater" link below. Then, go to the "How to use it" section to learn how adding one line of code to your plugin will implement Updater.

    Get Updater

    Features:

    • No more hassle! Never worry about configuring your Dropbox text files to the latest build's url, or forgetting to update external files again. Upload once to BukkitDev, and as soon as your file is approved clients will start downloading it, even if the approval comes at 4am and you're fast asleep.
    • Setup is as easy as copying a class and giving it your BukkitDev project slug. Updater will do the rest.
    • Ability to tag certain builds as non-update builds. For instance, on my Jenkins system every build is tagged with -DEV, so that people who are using it do not get switched to the official latest build, and can stay testing the pre-release. Simply edit the "noUpdateTag" array in the class to define what kind of builds should be left alone.
    • Don't hassle your users anymore. Server admins have enough on their hands, don't concern them with updates, because they just will /not/ update. From personal experience, I know that the only time I cared about a plugin update was when something broke. It's far too difficult to worry about a new file every day, but if you let Updater automatically install updates, your users will rejoice!
    • Be safe. EVERY file that Updater downloads has been approved by BukkitDev staff. Real humans go line-by-line through the code of each plugin that is approved on dev.bukkit.org, to verify it is free of any malicious code. Your user's shouldn't have to blindly accept your trust, you can instead show and prove to them that by using updater, you are keeping them secure.
    • Works with both .jar file and .zip file updates.
    -- Get Updater --


    How it works:

    - First, Updater connects to BukkitDev API and requests information about your project.

    - It then searches the information for the latest file, and obtains information about it like its name and version number.

    - Optionally, Updater will run a version check, comparing the newest file with the plugin's current version. NOTE: For this to work, your file titles must be named in this format: 'PluginName vVersionNumber', such as 'AntiCheat v1.0' (or simply 'v1.0', the name is not needed, but suggested). Here's a screenshot of how this should look, if done properly:
    File titles with proper version numbers (open)

    [​IMG]

    - Assuming that an update is needed, Updater will download the file from dev.bukkit.org and store it in the update folder. This is a folder defined in the bukkit.yml file where any stored jars will be switched with its currently-in-use counterpart when the system is reloaded or restarted. This means that the user does not need to worry about replacing the downloaded file with the current file; it's all done in the background.

    How to use it:

    If you are using Maven to manage your project you can use my Maven repository to get the dependency. To do this, edit your pom.xml to add the following repository:
    Code:
        <repositories>
            <repository>
                <id>gravity-repo</id>
                <url>http://repo.gravitydevelopment.net</url>
            </repository>
        </repositories>
    
    Then, add the following dependency:
    Code:
        <dependencies>
            <dependency>
                <groupId>net.gravitydevelopment.updater</groupId>
                <artifactId>updater</artifactId>
                <version>2.1</version>
            </dependency>
        </dependencies>
    
    Otherwise, you can use the traditional way and download the source code for Updater. Simply place this somewhere within your plugin's packages, and then switch over to your main class to get to work.

    As with most of my projects, I boast the fact that you only need one line of code added to your main class (the one that extends JavaPlugin) to make this work (along with my Updater class, of course), so here's what it is:

    Code:
    Updater updater = new Updater(this, id, this.getFile(), Updater.UpdateType.DEFAULT, false);
    That's it! This single line of code will literally keep the user updated for the rest of their life. Here's a breakdown of what all these values are:

    1) "this" - The plugin instance. I suggest using this in your onEnable() method, so that you can properly issue the 'this' keyword. Other methods that are called before onEnable() will not work (but anything after it, or that is called BY onEnable() does work).

    2) "id" - This is how Updater finds your project on BukkitDev. If you don't know what this is, follow the instructions on this wiki article.

    3) "this.getFile()" - The plugin's file, this is so that Updater can properly replace your plugin with the update when it is downloaded. Note that this is a protected value, and so it can only be accessed within your plugin's main class

    4) "Updater.UpdateType.DEFAULT" - This allows you to choose which type of update you would like to take place. Currently there are 3 options:
    - DEFAULT - Typically what you would want. Do an update check, and then if it's out of date download and install the latest update.
    - NO_VERSION_CHECK - In case you know you need (or want) to update, skip version checking and just download the latest file, regardless of any it's details.
    - NO_DOWNLOAD - In case you just want to do a version check. No files will be downloaded, but you still get information about the newest build on DBO, like it's version number and size.

    5) "false" - This is a value declaring whether you want Updater to announce the progress of the download, as it takes place. This is similar to what this output (to the console) will look like:
    Output (open)

    2012-08-29 16:30:56 [INFO] [AntiCheat] Enabling AntiCheat v1.3.6-DEV
    2012-08-29 16:30:57 [INFO] About to download a new update: AntiCheat v1.3.5
    2012-08-29 16:30:57 [INFO] Downloading update: 10% of 93738 bytes.
    2012-08-29 16:30:57 [INFO] Downloading update: 20% of 93738 bytes.
    2012-08-29 16:30:57 [INFO] Downloading update: 30% of 93738 bytes.
    2012-08-29 16:30:57 [INFO] Downloading update: 50% of 93738 bytes.
    2012-08-29 16:30:57 [INFO] Downloading update: 70% of 93738 bytes.
    2012-08-29 16:30:57 [INFO] Downloading update: 80% of 93738 bytes.
    2012-08-29 16:30:57 [INFO] Downloading update: 90% of 93738 bytes.
    2012-08-29 16:30:57 [INFO] Downloading update: 100% of 93738 bytes.
    2012-08-29 16:30:57 [INFO] Finished updating.

    If this option is true, and there is no update, there will be no output to the console.

    You can also see these values documented in JavaDocs here: http://gravitydevelopment.net/docs/updater/

    ------------------------------------------------------------------------------------------------------------------------------------
    NOTICE:
    As of Updater 2.0, a configuration file is created to allow server administrators to globally toggle updating for any plugin using this class. While this option does provide a convenient method for server admins to disable all Updater instances, Bukkit project submission guidelines still require that you make your plugin's Updater instance specifically toggleable with its own configuration option. This gives server administrators the opportunity to only disable the updating capabilities of one plugin in particular, should they choose to do so. You may read more about compliance with this policy here.
    ------------------------------------------------------------------------------------------------------------------------------------


    Expanding updater:

    Note: The following contains more advanced user information on controlling Updater. While Updater is very simple to use, it also gives a great deal of feedback and control to the developer if they want to use it. If you are just starting to develop plugins, it is recommended that you stop here and just use Updater as you have learned to use it so far. If you are an advanced user, you may continue on, but know that all of the following info is optional, and only necessary if you want to customize your experience.

    Now, of course you may want to know what the outcome of the process was, so you can inform the user or update some values in your plugin to reflect that it is now updated. This result can easily be obtained by using the "getResult()" call. This returns an UpdateResult that reflects what happened.​

    Code:
            Updater.UpdateResult result = updater.getResult();
            switch(result)
            {
                case SUCCESS:
                    // Success: The updater found an update, and has readied it to be loaded the next time the server restarts/reloads
                    break;
                case NO_UPDATE:
                    // No Update: The updater did not find an update, and nothing was downloaded.
                    break;
                case DISABLED:
                    // Won't Update: The updater was disabled in its configuration file.
                    break;
                case FAIL_DOWNLOAD:
                    // Download Failed: The updater found an update, but was unable to download it.
                    break;
                case FAIL_DBO:
                    // dev.bukkit.org Failed: For some reason, the updater was unable to contact DBO to download the file.
                    break;
                case FAIL_NOVERSION:
                    // No version found: When running the version check, the file on DBO did not contain the a version in the format 'vVersion' such as 'v1.0'.
                    break;
                case FAIL_BADID:
                    // Bad id: The id provided by the plugin running the updater was invalid and doesn't exist on DBO.
                    break;
                case FAIL_APIKEY:
                    // Bad API key: The user provided an invalid API key for the updater to use.
                    break;
                case UPDATE_AVAILABLE:
                  // There was an update found, but because you had the UpdateType set to NO_DOWNLOAD, it was not downloaded.
            }
    All these values, of course, are documented in easy-to-read HTML here: http://gravitydevelopment.net/docs/updater/

    You also may want to know information about the newest update. Some people prefer to have Updater run a version check ONLY (using UpdateType.NO_DOWNLOAD), then, if there is an update available, start notifying admins as they log in that there is a new version ready, with information like file size and version. An admin would then issue a command, and the developer would run Updater again but this time with UpdateType set to NO_VERSION_CHECK, thus downloading the newest build at the admin's request.

    We have a few methods available for you to use for this information. We already know that we can determine the outcome of the version check by calling getResult(), but here are some more methods you can call to get information about the newest file:

    - getLatestName() - Returns the name of the latest file you have uploaded to BukkitDev (Ex: "AntiCheat v1.5.9")
    - getLatestType() - Returns the type of the latest file you have uploaded to BukkitDev (Alpha, Beta, Release)
    - getLatestGameVersion() - Returns the compatible Game Version of the latest file you have uploaded to BukkitDev (Ex: "CB 1.6.2-R1.0")
    - getLatestFileLink() - Returns the link to the latest file you have uploaded.

    The scenario mentioned about would look something like this (pseudocode):

    Code:
    // In main class
    
    public static boolean update = false;
    public static String name = "";
    public static ReleaseType type = null;
    public static String version = "";
    public static String link = "";
    // You would want to make getter methods in your class, this is just for simplicity.
    
    public void onEnable()
    {
      Updater updater = new Updater(this, YOUR_ID_HERE, this.getFile(), Updater.UpdateType.NO_DOWNLOAD, false); // Start Updater but just do a version check
      update = updater.getResult() == Updater.UpdateResult.UPDATE_AVAILABLE; // Determine if there is an update ready for us
      name = updater.getLatestName(); // Get the latest name
      version = updater.getLatestGameVersion(); // Get the latest game version
      type = updater.getLatestType(); // Get the latest file's type
      link = updater.getLatestFileLink(); // Get the latest link
    }
    
    // In a listener class:
    
    @EventHandler
    public void onPlayerJoin(PlayerJoinEvent event)
    {
      Player player = event.getPlayer();
      if(player.hasPermission("foo.bar") && Main.update)
      {
        player.sendMessage("An update is available: " + Main.name + ", a " + Main.type + " for " + Main.version + " available at " + Main.link);
        // Will look like - An update is available: AntiCheat v1.5.9, a release for CB 1.6.2-R0.1 available at http://media.curseforge.com/XYZ
        player.sendMessage("Type /update if you would like to automatically update.");
      }
    }
    
    // And then later in a CommandExecutor class, when they type /update:
    
    Updater updater = new Updater(this, YOUR_ID_HERE, this.getFile(), Updater.UpdateType.NO_VERSION_CHECK, true); // Go straight to downloading, and announce progress to console.
    

     
    Last edited: May 6, 2016
    FisheyLP, Nathat23, Eathuis and 36 others like this.
  2. Offline

    r3nt3r

    I get error
     
  3. Offline

    Gravity Retired Staff

    Think so, yes.
    You can do whatever you like, it's open-source, feel free to fork and modify it
    Are you using the latest version? The one on github right now?
    The lines mentioned in that error don't really match up with the current version in a logical way.
     
  4. Offline

    r3nt3r

  5. Offline

    Gravity Retired Staff

    The reason I'm asking is because the line number the error is actually coming from is 493, which is in the "checkVersion" method. This would mean you have no version number in your plugin.yml. That's plausible, but not likely seeing as Bukkit displays 'Enabling rLot v1.0' on startup.

    However, it also shows the line number that the method is being called from as 204, which is not calling the "checkVersion" method but rather the "readFeed" method, so all this seems a little bit strange...
     
  6. Offline

    zack6849

    Question, does this also add to my download counter? or no?
     
  7. Offline

    Gravity Retired Staff

    It should, yes.
     
  8. Offline

    zack6849

    Okay, ^_^
     
  9. Offline

    r3nt3r

    Ok i fixed previous problem but now i have this code
    Code:
    loadConfiguration();
            final boolean updateEnable = getConfig().getBoolean("auto-update");
            if (updateEnable) {
                this.log.info(this.logPrefix + "Update");
                final Updater updater = new Updater(this, "rlot", this.getFile(), Updater.UpdateType.DEFAULT, false);
            } else {
                this.log.info(this.logPrefix + "No update");
                final Updater updater = new Updater(this, "rlot", this.getFile(), Updater.UpdateType.NO_DOWNLOAD, false);
            }
    and it's give me
    this.log.info(this.logPrefix + "Update");
    but the class doesn't update my plugin :(
     
  10. Offline

    zack6849

    Set the UpdateType to NO_VERSION_CHECK just to test.
     
  11. Offline

    r3nt3r

    Ok this time downloaded the update.

    Ok idk how but when i use default agian it's working :D
     
  12. Offline

    zack6849

    Make sure you did the following
    • Named the files like you're told in the original post
    • And actually have a file on bukkitdev that is newer than the one you are working on so it knows to download it.
     
  13. Offline

    kennylax12

    So far I have been absolutely loving this class that you made and I cannot thank you enough for making it! However, I am running into some interesting problems. I will first explain what I am doing and how I am doing it.

    I have had no issues with the class in all previous builds of my plugin, but now, since I re-wrote the entire plugin, I am running into some errors. In my config file I have an option that, by default, set to false. When it is set to false the plugin will prompt the user when the log in that there is a new version out and they should type /vx update to update it.
    Code:
    auto-update: false
    This has worked fine in the past, until now. The message does not show up in my latest build. This is my current setup: (No errors in console)
    Code:
    public void onPlayerJoin(PlayerJoinEvent event){
            final Player player = event.getPlayer();
            if(!player.hasPermission("vertex.update.info")){
                return;
            }
            if(!this.getConfig().getBoolean("auto-update")){
                return;
            }
            Updater updater = new Updater(this, "vertex", this.getFile(), Updater.UpdateType.NO_DOWNLOAD, false);
            update = updater.getResult() == Updater.UpdateResult.UPDATE_AVAILABLE; 
            name = updater.getLatestVersionString();
            size = updater.getFileSize(); 
            //String version = name.split(" ")[1].replaceAll("v", "");
            if(updater.getResult() == Updater.UpdateResult.UPDATE_AVAILABLE){
                player.sendMessage(ChatColor.YELLOW+"An update is available: " + Vertex.name + "(" + Vertex.size + " bytes)");
                player.sendMessage(ChatColor.YELLOW+"Type "+ChatColor.WHITE+"/vx update"+ChatColor.YELLOW+" to update.");
            }
        }
    The String version is there because that was my old method of looking for the latest version. When I log into the server as an OP, player with all permissions, or a player with just the permission node vertex.update.info I receive no message telling me about a new update. I have set the version of my plugin to a version number less than that of the one on BukkitDev, yet still no results.

    In case you need to know what happens when the player does /vx update
    Code:
    else if(args[0].equalsIgnoreCase("update")){
    if(plugin.getConfig().getBoolean("auto-update")){
    player.sendMessage(red+"Error: Self-Update must be set to false to use this command.");
    return true;
    }
    log.info("[PLAYER_COMMAND] "+player.getName()+": /vx update");
    plugin.updatePlugin();
    player.sendMessage(green+"Success! Updates will apply after a server restart.");
    Code:
    public void updatePlugin(){
            Updater updater = new Updater(this, "vertex", this.getFile(), Updater.UpdateType.NO_VERSION_CHECK, true);
        }
    I may be missing something silly here as I am tired of coding the same thing all of over, but I know it will be worth it. If you guys can spot anything then I would be very grateful! If you need any more information I will be happy to provide you with it.
     
  14. Offline

    Gravity Retired Staff

    Hi, I'm not sure exactly what your problem is just now, but I highly suggest that you do not run the Updater onPlayerLogin. Run it once when the server starts up and store the result if the auto-updater is enabled. Then check back with the original result to see the update status.
     
  15. Offline

    kennylax12

    Oddly enough this did fix the problem. This is what I am doing now:

    Code:
    if(this.getConfig().getBoolean("auto-update")){
                log.info("[Vertex] Self-Update enabled. Will check for updates.");
                Updater updater = new Updater(this, "vertex", this.getFile(), Updater.UpdateType.DEFAULT, false);
            }else{
                Updater updater = new Updater(this, "vertex", this.getFile(), Updater.UpdateType.NO_DOWNLOAD, false);
                if(updater.getResult() == Updater.UpdateResult.UPDATE_AVAILABLE){
                    name = updater.getLatestVersionString();
                    size = updater.getFileSize();
                    a.add(ChatColor.YELLOW+"An update is available: " + Vertex.name + "(" + Vertex.size + " bytes)");
                    a.add(ChatColor.YELLOW+"Type "+ChatColor.WHITE+"/vx update"+ChatColor.YELLOW+" to update.");
                }
            }
    Code:
    public void onPlayerJoin(PlayerJoinEvent event){
            Player player = event.getPlayer();
            if(!player.hasPermission("vertex.update.info")){
                return;
            }
            if(this.getConfig().getBoolean("auto-update")){
                return;
            }
            if(a.size() > 0){
                player.sendMessage(a.get(0));
                player.sendMessage(a.get(1));
            }
    And this works! If there is a better way of doing this then I'd be happy if you tell me! (I just coded this as a real fast fix.)
    As an additional note, I am still using the updatePlugin() method I stated before. I am assuming this is fine since you did not comment on it :)

    Once again I cannot thank you enough for creating this class and still supporting it! :D

     
    h31ix likes this.
  16. Offline

    Icyene

    h31ix One question about the proper version titles: say I have files like

    Code:
    ...................
    File v0.0.3B
    File v0.0.2B
    File v0.0.1B
    File v0.0.1A
    ...................
    
    Would that count as proper titles, or do I have to rename them to not have the letters at the end appended? Or modify the updater to do that?
     
  17. Offline

    Gravity Retired Staff

    Updater accepts any string as a version.
     
    Icyene likes this.
  18. Offline

    Icyene

    Thanks for the quick reply!
     
    h31ix likes this.
  19. Offline

    HON95

    Cool. :)
     
  20. Offline

    macguy8

    Are the java docs for this broken...? They aren't working for me...
     
  21. Offline

    Gravity Retired Staff

    Sorry about that, switched servers and forgot to update docs. Links have been fixed.
     
  22. Offline

    macguy8

    Thanks for your awesome system, and fixing that so quickly

    EDIT: You seemed to have changed the title for the links, and not the site they link to. Still accessible if you type it n, but clicking the link is still broken

    EDIT by Moderator: merged posts, please use the edit button instead of double posting.
     
    Last edited by a moderator: Jan 4, 2016
  23. Offline

    Gravity Retired Staff

    Oh, I just missed two of them, now they're fixed.
     
  24. Offline

    nala3

    Awesome, thanks h31ix. This is really useful :) On a side note, my FindBugs warnings shot up after I added this :p Took me a bit to fix it all.
    [​IMG]
     
  25. Offline

    exload

    I just wanted to thank you again for this awesome class! It was a major time saver and I use it on all of my plugins!
    A simple thanks :)
     
  26. Offline

    bob7

    This is great! So much better then checking github for the latest version number!
    Using with HawkEye Reloaded :)
     
    h31ix likes this.
  27. Offline

    zack6849

    Umm h31ix wat.
    Code:
     
    00:28:08 [INFO] [SuperLogger] Enabling SuperLogger v1.2
    00:28:10 [INFO] [SuperLogger] About to download a new update: SuperLogger v1.1
    00:28:10 [INFO] [SuperLogger] Downloading update: 80% of 24085 bytes.
    00:28:10 [INFO] [SuperLogger] Downloading update: 100% of 24085 bytes.
    00:28:10 [INFO] [SuperLogger] Finished updating.
    
    in my plugin.yml
    version: 1.2

    in my plugin itself
    Code:
    boolean update = getConfig().getBoolean("auto-update");
    if(update){
        Updater updater = new Updater(this, "super-logger", this.getFile(),Updater.UpdateType.DEFAULT, true);
    }
    
    naming for the plugin page.
    [​IMG]

    halp :'(
     
  28. Offline

    Gravity Retired Staff

    Why should you be running a build that isn't on DBO?
    If you're doing development, you need to add the -DEV or -PRE tag to the end of the version, and it will not do an update on it.
     
  29. Offline

    zack6849

    Where would i add said tag at? in the plugin.yml?
     
  30. Offline

    p000ison

    I'm not sure since I did not look long through the code, but I think you could/should make the inner classes static, because you do not use data from the parent classes. Just ignore this if you use it :p
     
  31. Offline

    md_5

    /me wonders why the enum has magic numbers the same as their ordinals.
     
Thread Status:
Not open for further replies.

Share This Page