1 package com.nexuiz.demorecorder.application.plugins.impl.sample;
3 import java.util.Properties;
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;
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.
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!
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
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!
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.
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.
45 public class SamplePlugin implements EncoderPlugin {
48 * Do not put the word "plug-in" in here, that would be redundant.
50 private static final String PLUGIN_NAME = "Sample";
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.
56 private static class Preferences {
58 * Lets start with GLOBAL settings which will be seen in the Preferences dialog of the NDR
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"
63 public static final String SAMPLE_SETTING = "Some sample setting";
66 * Now we define the order in which we want these to be shown.
68 public static final String[] GLOBAL_PREFERENCES_ORDER = {
73 //job-specific preferences
74 public static final String IN_USE_FOR_THIS_JOB = "Do something for this job";
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.
80 public static Properties globalDefaultPreferences = new Properties();
81 public static void createPreferenceDefaultValues() {
82 globalDefaultPreferences.setProperty(ENABLED, "false");
83 globalDefaultPreferences.setProperty(SAMPLE_SETTING, "filechooser");
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
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)
96 private DemoRecorderApplication appLayer;
99 * You must only have a default constructor without parameters!
101 public SamplePlugin() {
102 Preferences.createPreferenceDefaultValues();
108 public Properties getGlobalPreferences() {
109 return Preferences.globalDefaultPreferences;
113 public String[] getGlobalPreferencesOrder() {
114 return Preferences.GLOBAL_PREFERENCES_ORDER;
118 public Properties getJobSpecificPreferences() {
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.
124 Properties preferences = new Properties();
125 preferences.setProperty(Preferences.IN_USE_FOR_THIS_JOB, "true");
130 public String[] getJobSpecificPreferencesOrder() {
131 String[] order = {Preferences.IN_USE_FOR_THIS_JOB};
136 public String getName() {
141 public void setApplicationLayer(DemoRecorderApplication appLayer) {
142 this.appLayer = appLayer;
146 public boolean isEnabled() {
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.
152 String enabledString = this.appLayer.getPreferences().getProperty(PLUGIN_NAME, Preferences.ENABLED);
153 return Boolean.valueOf(enabledString);
157 public void executeEncoder(RecordJob job) throws EncoderPluginException {
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:
163 if (!this.isEnabled()) {
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)");
172 if (!job.getActualVideoDestination().exists()) {
173 throw new EncoderPluginException("Could not locate recorded video file (source) at location "
174 + job.getActualVideoDestination().getAbsolutePath());
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;"
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.
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.
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.