Changeset 3495 for trunk/doc/src/docbook/developerdoc/plugin_developer.xml

Timestamp:

Jun 14, 2007, 2:36:26 PM (15 years ago)

Author:

Nicklas Nordborg

Message:

References #625. Major features are now in place. It's a bit tricky to update the isInContext
method on all plug-ins. I need more testing time to verify that all works before I close the
ticket.

File:

• trunk/doc/src/docbook/developerdoc/plugin_developer.xml (modified) (4 diffs)

trunk/doc/src/docbook/developerdoc/plugin_developer.xml

@@ -711 +711 @@
               <para>
                 This method is called to check if a particular item is usable for the
-                plug-in. This method is only invoked from the single-item view.
-                Thus, <code>context.getType()</code> always returns 
-                <constant>Type.ITEM</constant>, and <code>context.getItem()</code>
-                returns a value corresponding to the type of item that is passed
-                in the <varname>item</varname> parameter. Here is an example:
-                
-                <informalexample>
+                plug-in. This method is invoked to check if a plug-in can be used
+                in a given context. If invoked from a list context the <parameter>item</parameter>
+                parameter is <constant>null</constant>.  
+                The plug-in should return <constant>null</constant> if it
+                finds that it can be used. If the plug-in can't be used it
+                must decide if the reason should be a warning or an error condition.
+              </para>
+              
+              <para>
+                A warning is issued by returning a string with the warning
+                message. It should be used when the plug-in can't be used because
+                it is unrelated to the current task. For example, a plug-in for
+                importing Genepix data should return a warning when somebody wants
+                to import data to an Agilent raw bioassay.
+              </para>
+              
+              <para>
+                An error message is issued by throwing an exception. This 
+                should be used when the plug-in is related to the current task
+                but still can't do what it is supposed to do. For example,
+                trying to import raw data if the logged in user doesn't have
+                write permission to the raw bioassay.
+              </para>
+              
+              <para>
+                As a rule of thumb, if there is a chance that another plug-in
+                might be able to perform the same task a warning should be used.
+                If it is guaranteed that no other plug-in can do it an error
+                message should be used.
+              </para>
+              
+              <note>
                 <para>
-                The user has selected a specific sample and the client
-                application is now displaying information about that sample. 
-                Thus, our
-                <varname>GuiContext</varname> = 
-                (<constant>Item.SAMPLE</constant>,
-                <constant>Type.ITEM</constant>). 
-                
-                Now, the client application asks for a list of plug-ins supporting
-                this context and for each one in the list calls this method with the
-                current sample as the value of the <varname>item</varname> parameter. 
+                The contract of this method was changed in in BASE 2.4
+                to allow warning and error level message. Prior to BASE
+                2.4 all messages were treated as error message. We recommend
+                that existing plug-ins are updated to throw exception to indicate
+                error-level messages since the default is to not show 
+                warning messages to users.
                 </para>
-                </informalexample>
-
-                If the plug-in can do whatever it is supposed to do it should
-                return null, otherwise it should return a string with a message
-                explaining why it cannot.
-              </para>
+              </note>
+              
               <para>
                 Here is a real example from the
@@ -747 +764 @@
                 <constant>Type.ITEM</constant>), 
                 
-                but the plug-in can only import data if there is no data already, and
+                but the plug-in can only import data if the logged in user has write permission,
+                there is no data already, and
                 if the raw bioassay has the same raw data type as the plug-in has been
                 configured for.
@@ -758 +776 @@
 <programlisting>/**
    Returns null if the item is a {@link RawBioAssay} of the correct
-   {@link RawDataType} and does not already have spots.
+   {@link RawDataType} and doesn't already have spots.
+   @throws PermissionDeniedException If the raw bioasssay already has raw data
+   or if the logged in user doesn't have write permission
 */
 public String isInContext(GuiContext context, Object item)
@@ -775 +795 @@
       RawBioAssay rba = (RawBioAssay)item;
       String rawDataType = (String)configuration.getValue("rawDataType");
-      if (rba.getSpots() > 0)
-      {
-         message = "The raw bioassay already has spots: " + rba.getName();
-      }
-      else if (!rba.getRawDataType().getId().equals(rawDataType))
+      RawDataType rdt = rba.getRawDataType();
+      if (!rdt.getId().equals(rawDataType))
       {
          message = "Unsupported raw data type: " + rba.getRawDataType().getName();
+      }
+      else if (!rdt.isStoredInDb())
+      {
+         message = "Raw data for raw data type '" + rdt + "' is not stored in the database";
+      }
+      else if (rba.hasData())
+      {
+         throw new PermissionDeniedException("The raw bioassay already has data.");
+      }
+      else
+      {
+         rba.checkPermission(Permission.WRITE);
       }
    }