001/*
002        $Id: Plugin.java 3207 2009-04-09 06:48:11Z gregory $
003
004        Copyright (C) 2006 Gregory Vincic, Olle Mansson
005        Copyright (C) 2007 Gregory Vincic
006
007        This file is part of Proteios.
008        Available at http://www.proteios.org/
009
010        Proteios is free software; you can redistribute it and/or modify it
011        under the terms of the GNU General Public License as published by
012        the Free Software Foundation; either version 2 of the License, or
013        (at your option) any later version.
014
015        Proteios is distributed in the hope that it will be useful, but
016        WITHOUT ANY WARRANTY; without even the implied warranty of
017        MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
018        General Public License for more details.
019
020        You should have received a copy of the GNU General Public License
021        along with this program; if not, write to the Free Software
022        Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA
023        02111-1307, USA.
024*/
025package org.proteios.core.plugin;
026
027import org.proteios.core.BaseException;
028import org.proteios.core.ProgressReporter;
029import org.proteios.core.SessionControl;
030import java.util.HashMap;
031import java.util.Map;
032
033/**
034        This interface must be implemented by all plugins to Proteios.
035        A plugin must also define a default public no-argument
036        constructor.
037
038        <p>
039        When a plugin is installed into Proteios the core will use
040        the following sequence to store all meta-information about the plugin
041        in the database:
042        <ol>
043        <li>Create a plugin object, using the default constructor
044        <li>Call the {@link #getMainType()} and {@link #getAbout()} methods
045        <li>Check if the plugin inmplements the {@link InteractivePlugin}
046                and if it does, call the {@link InteractivePlugin#getGuiContexts()}
047                method.
048        <li>Check which other interfaces the plugin implements, and
049                link to {@link org.proteios.core.PluginType} as appropriate
050        </ol>
051
052        <p>
053        When a plugin is executed using a the request/response scheme the core will
054        use the following sequence:
055        <ol>
056        <li>Create a plugin object, using the default constructor
057        <li>Call the {@link #init(SessionControl, ParameterValues, ParameterValues)} method
058                which gives the plugin access to it's configuration and job-specific parameters
059        <li>Call the {@link #run(Request, Response, ProgressReporter)} method to let
060                the plugin do it's work
061        <li>Call {@link #done()} to let the plugin clean up after itself
062        <li>After <code>done</code> has been called, the plugin instance is not
063                reused again
064        </ul>
065
066        @author Nicklas, Enell
067        @version 2.0
068        @base.modified $Date: 2009-04-09 08:48:11 +0200 (Thu, 09 Apr 2009) $
069*/
070public interface Plugin
071{
072        /**
073                Get the type of the plugin. This method must always
074                return the same value.
075                @return One of the defined types
076        */
077        public MainType getMainType();
078
079        /**
080                Get information about the plugin, such as
081                name, version, authors, etc.
082                @return An {@link About} object
083        */
084        public About getAbout();
085
086        /**
087                This method is called right after the plugin object has been constructed 
088                to pass the configuration and job parameters to the plugin. The 
089                <code>ParameterValues</code> parameters can be null if no parameters exists.
090
091                @param sc A <code>SessionControl</code> object that the plugin
092                        can use to communicate with the core.
093                @param configuration The configuration parameters for the plugin
094                @param job The job parameters for the plugin
095                @throws BaseException if there is an error.
096        */
097        public void init(SessionControl sc, ParameterValues configuration, ParameterValues job)
098                throws BaseException;
099
100        /**
101                Run the plugin. If a progress reporter object is passed it is 
102                recommended that the plugin makes use of it.
103
104                @param request Request object with the command and parameters
105                @param response Response object in for the plugin to response
106                        through
107                @param progress A {@link ProgressReporter} where the plugin can report
108                        its progess, can be null
109        */
110        public void run(Request request, Response response, ProgressReporter progress);
111        
112        /**
113                This method is called when the core is finished
114                with the plugin object. The plugin should clean up
115                and close any resources it has aquired.
116        */
117        public void done();
118
119        public enum MainType
120        {
121                IMPORT(1, "Import"),
122                EXPORT(2, "Export"),
123                INTENSITY(3, "Intensity"),
124                ANALYZE(4, "Analyze"),
125                OTHER(5, "Other"),
126                CONVERT(6, "Convert");
127
128                /**
129                        Maps an integer to a type.
130                */
131                private static final Map<Integer, MainType> valueMapping = new HashMap<Integer, MainType>();
132                static
133                {
134                        for(MainType type : MainType.values())
135                        {
136                                MainType t = valueMapping.put(type.getValue(), type);
137                                assert t == null : "Another type with the value "+type.getValue()+" already exists";
138                        }
139                }
140                
141                public static MainType fromValue(int value)
142                {
143                        MainType type = valueMapping.get(value);
144                        assert type != null : "type == null for value "+value;
145                        return type;
146                }
147                
148                private final int value;
149                private final String displayValue;
150                private MainType(int value, String displayValue)
151                {
152                        this.value = value;
153                        this.displayValue = displayValue;
154                }
155
156                public int getValue()
157                {
158                        return value;
159                }
160
161                @Override
162                public String toString()
163                {
164                        return displayValue;
165                }
166        }
167}