[xonotic/xonotic.git] /

package com.nexuiz.demorecorder.application.plugins.impl.sample;\r
\r
import java.util.Properties;\r
\r
import com.nexuiz.demorecorder.application.DemoRecorderApplication;\r
import com.nexuiz.demorecorder.application.jobs.RecordJob;\r
import com.nexuiz.demorecorder.application.plugins.EncoderPlugin;\r
import com.nexuiz.demorecorder.application.plugins.EncoderPluginException;\r
\r
/**\r
 * This is a sample plug-in implementation. It does not really do anything, but it\r
 * is supposed to show you how to implement a plug-in and where to do what.\r
 * \r
 * First of all, it is important that your final jar file (you can have Maven create\r
 * it for you) contains the META-INF folder (it will have that one anyway), and within\r
 * that folder you must have the folder "services", in which you must have a file called\r
 * com.nexuiz.demorecorder.application.plugins.EncoderPlugin (this is the fully\r
 * qualified name of the interface you need to implement, EncoderPlugin).\r
 * This file needs to contain just one line: the fully qualified name to your\r
 * implementation class!\r
 * \r
 * Okay. The Nexuiz Demo Recorder (NDR) gives your plug-in 2 kinds of possibilities to\r
 * configure it ("set it up") from within the NDR. Configuring the plug-in is also \r
 * referred to as "setting preferences". There are \r
 * - Global preferences: these will be shown in the "Preferences" dialog of the NDR\r
 * - Job-specific preferences: these will be shown in the dialog you get when creating\r
 *   new jobs or templates, or when editing them\r
 * \r
 * Once the NDR loaded your plug-in, the first thing it will do is to call \r
 * setApplicationLayer(), handing your plug-in the reference to the app-layer. Make sure that\r
 * you save it in a private member variable!\r
 * \r
 * NDR will ask your plug-in to tell it about its global and job-specific preferences that exist.\r
 * For each of these 2 kinds of preferences it will also ask you for the order in which you want\r
 * these settings to appear in dialogs.\r
 * \r
 * The methods that ask you to return a Properties object: create a new Properties object and fill\r
 * it with KEYS (that identify the setting), and VALUES (reasonable default values). The app-layer\r
 * will save these "new" settings in the app_preferences.xml in the "settings" folder once NDR\r
 * is closed (this applies only to the global settings!). That just means that, later on, to figure\r
 * out whether the user changed settings from their default value, you need to ask the app-layer\r
 * for its preferences object (that might have been manipulated by the user using the GUI) and look\r
 * for "your" settings in that Properties object. A good example is the isEnabled() method.\r
 */\r
public class SamplePlugin implements EncoderPlugin {\r
        \r
        /**\r
         *  Do not put the word "plug-in" in here, that would be redundant.\r
         */\r
        private static final String PLUGIN_NAME = "Sample";\r
        \r
        /**\r
         * Here we store our preferences. It is not necessary that these are in a inner-class, do it in\r
         * your way if you want.\r
         */\r
        private static class Preferences {\r
                /*\r
                 * Lets start with GLOBAL settings which will be seen in the Preferences dialog of the NDR\r
                 */\r
                public static final String ENABLED = "Enabled"; //we will need this! "Enabled" means that\r
                                                                        //that the preferences dialog will show the exact word "Enabled"\r
                \r
                public static final String SAMPLE_SETTING = "Some sample setting";\r
                \r
                /*\r
                 * Now we define the order in which we want these to be shown.\r
                 */\r
                public static final String[] GLOBAL_PREFERENCES_ORDER = {\r
                        ENABLED,\r
                        SAMPLE_SETTING\r
                };\r
                \r
                //job-specific preferences\r
                public static final String IN_USE_FOR_THIS_JOB = "Do something for this job";\r
                \r
                /*\r
                 * OK, so far we have actually only created labels. But we also need default values\r
                 * So let's have a function that sets the default values up.\r
                 */\r
                public static Properties globalDefaultPreferences = new Properties();\r
                public static void createPreferenceDefaultValues() {\r
                        globalDefaultPreferences.setProperty(ENABLED, "false");\r
                        globalDefaultPreferences.setProperty(SAMPLE_SETTING, "filechooser");\r
                        /*\r
                         * Note that the values for the defaults can be:\r
                         * - "true" or "false", in this case the GUI will show a check-box\r
                         * - "filechooser", in this case the GUI will show a button that allows the user to select\r
                         *    a file\r
                         * - anything else (also empty string if you like): will show a text field in the GUI\r
                         *   (you are in charge of parsing it)\r
                         */\r
                }\r
                \r
        }\r
        \r
        private DemoRecorderApplication appLayer;\r
        \r
        /**\r
         * You must only have a default constructor without parameters!\r
         */\r
        public SamplePlugin() {\r
                Preferences.createPreferenceDefaultValues();\r
        }\r
\r
        \r
\r
        @Override\r
        public Properties getGlobalPreferences() {\r
                return Preferences.globalDefaultPreferences;\r
        }\r
\r
        @Override\r
        public String[] getGlobalPreferencesOrder() {\r
                return Preferences.GLOBAL_PREFERENCES_ORDER;\r
        }\r
\r
        @Override\r
        public Properties getJobSpecificPreferences() {\r
                /*\r
                 * This method is called whenever the dialog to create new jobs/templates (or edit them)\r
                 * is opened. This means that you can dynamically create the returned Properties object\r
                 * if you like, or you could of course also return something static.\r
                 */\r
                Properties preferences = new Properties();\r
                preferences.setProperty(Preferences.IN_USE_FOR_THIS_JOB, "true");\r
                return preferences;\r
        }\r
\r
        @Override\r
        public String[] getJobSpecificPreferencesOrder() {\r
                String[] order = {Preferences.IN_USE_FOR_THIS_JOB};\r
                return order;\r
        }\r
\r
        @Override\r
        public String getName() {\r
                return PLUGIN_NAME;\r
        }\r
        \r
        @Override\r
        public void setApplicationLayer(DemoRecorderApplication appLayer) {\r
                this.appLayer = appLayer;\r
        }\r
\r
        @Override\r
        public boolean isEnabled() {\r
                /*\r
                 * Here we get the Properties object of the app-layer. Notice that this is actually a\r
                 * NDRPreferences object. It has a new method getProperty(String category, String key).\r
                 * The category is the name of our plug-in. The key is obviously our own ENABLED key.\r
                 */\r
                String enabledString = this.appLayer.getPreferences().getProperty(PLUGIN_NAME, Preferences.ENABLED);\r
                return Boolean.valueOf(enabledString);\r
        }\r
        \r
        @Override\r
        public void executeEncoder(RecordJob job) throws EncoderPluginException {\r
                /*\r
                 * This is where the party gets started.\r
                 * Of course you need to check whether your plug-in is enabled by the user, and whether the\r
                 * job-specific settings are set correctly. So let's do this now:\r
                 */\r
                if (!this.isEnabled()) {\r
                        return;\r
                }\r
                \r
                if (job.getActualVideoDestination() == null) {\r
                        //should never happen... but just to make sure!\r
                        throw new EncoderPluginException("Actual video destination is not set (should have been set when processing the job)");\r
                }\r
                \r
                if (!job.getActualVideoDestination().exists()) {\r
                        throw new EncoderPluginException("Could not locate recorded video file (source) at location "\r
                                        + job.getActualVideoDestination().getAbsolutePath());\r
                }\r
                \r
                //check for a job-specific setting ... this time we need it from the job:\r
                Properties jobSpecificSettings = job.getEncoderPluginSettings(this);\r
                String isEnabled = jobSpecificSettings.getProperty(Preferences.IN_USE_FOR_THIS_JOB);\r
                if (!Boolean.valueOf(isEnabled)) {\r
                        //the job does not want our plug-in to be executed, d'oh\r
                        throw new EncoderPluginException("We are not enabled to do anything for this job :-(");\r
                        //of course in a real implementation, instead of throwing an exception we'd just "return;"\r
                }\r
                \r
                /*\r
                 * Now we can start doing the work. What you'll normally do is to construct a big string that you then have executed\r
                 * Have a look at the VirtualDub plug-in implementation to see how I did it.\r
                 * \r
                 * IMPORTANT: unless you parse the output of the console when executing a shell command (to check whether\r
                 * the encoder threw error messages at you), it is recommended that you create a log file of each job.\r
                 * The VirtualDub plug-in also provides an example of how to do that.\r
                 * \r
                 * Also notice the use of the EncoderPluginException. Whenever something goes wrong, throw this exception.\r
                 * Note that there is also another constructor EncoderPluginException(String message, Throwable t) where you\r
                 * can attach the original exception.\r
                 */\r
        }\r
\r
        \r
\r
}\r