misc/tools/NexuizDemoRecorder/plugins/sample/src/main/java/com/nexuiz/demorecorder/application/plugins/impl/sample/SamplePlugin.java

   1 package com.nexuiz.demorecorder.application.plugins.impl.sample;
   2
   3 import java.util.Properties;
   4
   5 import com.nexuiz.demorecorder.application.DemoRecorderApplication;
   6 import com.nexuiz.demorecorder.application.jobs.RecordJob;
   7 import com.nexuiz.demorecorder.application.plugins.EncoderPlugin;
   8 import com.nexuiz.demorecorder.application.plugins.EncoderPluginException;
   9
  10 /**
  11  * This is a sample plug-in implementation. It does not really do anything, but it
  12  * is supposed to show you how to implement a plug-in and where to do what.
  13  *
  14  * First of all, it is important that your final jar file (you can have Maven create
  15  * it for you) contains the META-INF folder (it will have that one anyway), and within
  16  * that folder you must have the folder "services", in which you must have a file called
  17  * com.nexuiz.demorecorder.application.plugins.EncoderPlugin (this is the fully
  18  * qualified name of the interface you need to implement, EncoderPlugin).
  19  * This file needs to contain just one line: the fully qualified name to your
  20  * implementation class!
  21  *
  22  * Okay. The Nexuiz Demo Recorder (NDR) gives your plug-in 2 kinds of possibilities to
  23  * configure it ("set it up") from within the NDR. Configuring the plug-in is also
  24  * referred to as "setting preferences". There are
  25  * - Global preferences: these will be shown in the "Preferences" dialog of the NDR
  26  * - Job-specific preferences: these will be shown in the dialog you get when creating
  27  *   new jobs or templates, or when editing them
  28  *
  29  * Once the NDR loaded your plug-in, the first thing it will do is to call
  30  * setApplicationLayer(), handing your plug-in the reference to the app-layer. Make sure that
  31  * you save it in a private member variable!
  32  *
  33  * NDR will ask your plug-in to tell it about its global and job-specific preferences that exist.
  34  * For each of these 2 kinds of preferences it will also ask you for the order in which you want
  35  * these settings to appear in dialogs.
  36  *
  37  * The methods that ask you to return a Properties object: create a new Properties object and fill
  38  * it with KEYS (that identify the setting), and VALUES (reasonable default values). The app-layer
  39  * will save these "new" settings in the app_preferences.xml in the "settings" folder once NDR
  40  * is closed (this applies only to the global settings!). That just means that, later on, to figure
  41  * out whether the user changed settings from their default value, you need to ask the app-layer
  42  * for its preferences object (that might have been manipulated by the user using the GUI) and look
  43  * for "your" settings in that Properties object. A good example is the isEnabled() method.
  44  */
  45 public class SamplePlugin implements EncoderPlugin {
  46
  47         /**
  48          *  Do not put the word "plug-in" in here, that would be redundant.
  49          */
  50         private static final String PLUGIN_NAME = "Sample";
  51
  52         /**
  53          * Here we store our preferences. It is not necessary that these are in a inner-class, do it in
  54          * your way if you want.
  55          */
  56         private static class Preferences {
  57                 /*
  58                  * Lets start with GLOBAL settings which will be seen in the Preferences dialog of the NDR
  59                  */
  60                 public static final String ENABLED = "Enabled"; //we will need this! "Enabled" means that
  61                                                                         //that the preferences dialog will show the exact word "Enabled"
  62
  63                 public static final String SAMPLE_SETTING = "Some sample setting";
  64
  65                 /*
  66                  * Now we define the order in which we want these to be shown.
  67                  */
  68                 public static final String[] GLOBAL_PREFERENCES_ORDER = {
  69                         ENABLED,
  70                         SAMPLE_SETTING
  71                 };
  72
  73                 //job-specific preferences
  74                 public static final String IN_USE_FOR_THIS_JOB = "Do something for this job";
  75
  76                 /*
  77                  * OK, so far we have actually only created labels. But we also need default values
  78                  * So let's have a function that sets the default values up.
  79                  */
  80                 public static Properties globalDefaultPreferences = new Properties();
  81                 public static void createPreferenceDefaultValues() {
  82                         globalDefaultPreferences.setProperty(ENABLED, "false");
  83                         globalDefaultPreferences.setProperty(SAMPLE_SETTING, "filechooser");
  84                         /*
  85                          * Note that the values for the defaults can be:
  86                          * - "true" or "false", in this case the GUI will show a check-box
  87                          * - "filechooser", in this case the GUI will show a button that allows the user to select
  88                          *    a file
  89                          * - anything else (also empty string if you like): will show a text field in the GUI
  90                          *   (you are in charge of parsing it)
  91                          */
  92                 }
  93
  94         }
  95
  96         private DemoRecorderApplication appLayer;
  97
  98         /**
  99          * You must only have a default constructor without parameters!
 100          */
 101         public SamplePlugin() {
 102                 Preferences.createPreferenceDefaultValues();
 103         }
 104
 105
 106
 107         @Override
 108         public Properties getGlobalPreferences() {
 109                 return Preferences.globalDefaultPreferences;
 110         }
 111
 112         @Override
 113         public String[] getGlobalPreferencesOrder() {
 114                 return Preferences.GLOBAL_PREFERENCES_ORDER;
 115         }
 116
 117         @Override
 118         public Properties getJobSpecificPreferences() {
 119                 /*
 120                  * This method is called whenever the dialog to create new jobs/templates (or edit them)
 121                  * is opened. This means that you can dynamically create the returned Properties object
 122                  * if you like, or you could of course also return something static.
 123                  */
 124                 Properties preferences = new Properties();
 125                 preferences.setProperty(Preferences.IN_USE_FOR_THIS_JOB, "true");
 126                 return preferences;
 127         }
 128
 129         @Override
 130         public String[] getJobSpecificPreferencesOrder() {
 131                 String[] order = {Preferences.IN_USE_FOR_THIS_JOB};
 132                 return order;
 133         }
 134
 135         @Override
 136         public String getName() {
 137                 return PLUGIN_NAME;
 138         }
 139
 140         @Override
 141         public void setApplicationLayer(DemoRecorderApplication appLayer) {
 142                 this.appLayer = appLayer;
 143         }
 144
 145         @Override
 146         public boolean isEnabled() {
 147                 /*
 148                  * Here we get the Properties object of the app-layer. Notice that this is actually a
 149                  * NDRPreferences object. It has a new method getProperty(String category, String key).
 150                  * The category is the name of our plug-in. The key is obviously our own ENABLED key.
 151                  */
 152                 String enabledString = this.appLayer.getPreferences().getProperty(PLUGIN_NAME, Preferences.ENABLED);
 153                 return Boolean.valueOf(enabledString);
 154         }
 155
 156         @Override
 157         public void executeEncoder(RecordJob job) throws EncoderPluginException {
 158                 /*
 159                  * This is where the party gets started.
 160                  * Of course you need to check whether your plug-in is enabled by the user, and whether the
 161                  * job-specific settings are set correctly. So let's do this now:
 162                  */
 163                 if (!this.isEnabled()) {
 164                         return;
 165                 }
 166
 167                 if (job.getActualVideoDestination() == null) {
 168                         //should never happen... but just to make sure!
 169                         throw new EncoderPluginException("Actual video destination is not set (should have been set when processing the job)");
 170                 }
 171
 172                 if (!job.getActualVideoDestination().exists()) {
 173                         throw new EncoderPluginException("Could not locate recorded video file (source) at location "
 174                                         + job.getActualVideoDestination().getAbsolutePath());
 175                 }
 176
 177                 //check for a job-specific setting ... this time we need it from the job:
 178                 Properties jobSpecificSettings = job.getEncoderPluginSettings(this);
 179                 String isEnabled = jobSpecificSettings.getProperty(Preferences.IN_USE_FOR_THIS_JOB);
 180                 if (!Boolean.valueOf(isEnabled)) {
 181                         //the job does not want our plug-in to be executed, d'oh
 182                         throw new EncoderPluginException("We are not enabled to do anything for this job :-(");
 183                         //of course in a real implementation, instead of throwing an exception we'd just "return;"
 184                 }
 185
 186                 /*
 187                  * Now we can start doing the work. What you'll normally do is to construct a big string that you then have executed
 188                  * Have a look at the VirtualDub plug-in implementation to see how I did it.
 189                  *
 190                  * IMPORTANT: unless you parse the output of the console when executing a shell command (to check whether
 191                  * the encoder threw error messages at you), it is recommended that you create a log file of each job.
 192                  * The VirtualDub plug-in also provides an example of how to do that.
 193                  *
 194                  * Also notice the use of the EncoderPluginException. Whenever something goes wrong, throw this exception.
 195                  * Note that there is also another constructor EncoderPluginException(String message, Throwable t) where you
 196                  * can attach the original exception.
 197                  */
 198         }
 199
 200
 201
 202 }