Initialization

From Apache OpenOffice Wiki
Jump to: navigation, search



A job is initialized by a call to its main interface method, which starts the job. For synchronous jobs, the execution environment calls <idlml>com.sun.star.task.XJob:execute</idlml>(), whereas asynchronous jobs are run through <idlml>com.sun.star.task.XAsyncJob:executeAsync</idlml>().

Both methods take one parameter Arguments, which is a sequence of com.sun.star.beans.NamedValue structs. This sequence describes the job context.

It contains the environment where the job is running, which tells if the job was called by the job executor, the dispatch framework or the global event broadcaster service, and possibly provides a frame or a document model for the job to work with.

Tip.png Section Implementation shows how to use a frame to get its associated document model.


The Arguments parameter also yields configuration data, if the job has been configured in the configuration branch org.openoffice.Office.Jobs. This data is separated into basic configuration and additional arguments stored in the configuration. The job configuration is described in section Configuration.

Finally, Arguments can contain dynamic parameters given to the job at runtime. For instance, if a job has been called by the dispatch framework, and the dispatched command URL used parameters, these parameters can be passed on to the job through the execution arguments.

The following table shows the exact specification for the execution Arguments:

Elements of the Execution Arguments Sequence
Environment sequence< com.sun.star.beans.NamedValue >. Contains environment data. The following named values are defined:
EnvType string. Determines in which environment a job is executed. Defined Values: "EXECUTOR": job has been executed by a call to trigger() at the job executor "DISPATCH": job is dispatched as vnd.sun.star.job: URL "DOCUMENTEVENT": job has been executed by the global event broadcaster mechanism
EventName [optional] string. Only exists, if EnvType is "EXECUTOR" or "DOCUMENTEVENT". Contains the name of the event for which this job was registered in configuration. During runtime, this information can be used to handle different function sets by the same component implementation.
Frame [optional] com.sun.star.frame.XFrame. Only exists, if EnvType is "DISPATCH". Contains the frame context of this job. Furthermore, the sub list DynamicData can contain the optional argument list of the corresponding com.sun.star.frame.XDispatch:dispatch() request.
Model [optional] com.sun.star.frame.XModel. Only exists, if EnvType is "DOCUMENTEVENT". Contains the document model that can be used by the job.
Config [optional] [sequence< com.sun.star.beans.NamedValue >]. Contains the generic set of job configuration properties as described in Configuration but not the job specific data set. That is, this sub list only includes the properties Alias and Service, not the property Arguments. The property Arguments is reflected in the element JobConfig (see next element below)

Note: this sub list only exists if the job is configured with this data.

Alias string. This property is declared as the name of the corresponding set node in the configuration set Jobs. It must be a unique name, which represents the structured information of a job.
Service string. Represents the UNO implementation name of the job component.
JobConfig [optional] [sequence< com.sun.star.beans.NamedValue >]

This sub list contains the job-specific set of configuration data as specified in the Arguments property of the job configuration. Its items depend on the job implementation. Note: this sub list only exists if the job is configured with this data.

DynamicData [optional] [sequence< com.sun.star.beans.NamedValue >]. Contains optional parameters of the call that started the execution of this job. In particular, it can include the parameters of a com.sun.star.frame.XDispatch:dispatch() request, if Environment-EnvType is "DISPATCH"

The following example shows how a job can analyze the given arguments and how the environment in which the job is executed can be detected:

  public synchronized java.lang.Object execute(com.sun.star.beans.NamedValue[] lArgs)
          throws com.sun.star.lang.IllegalArgumentException, com.sun.star.uno.Exception {
 
      // extract all possible sub list of given argument list
      com.sun.star.beans.NamedValue[] lGenericConfig = null;
      com.sun.star.beans.NamedValue[] lJobConfig = null;
      com.sun.star.beans.NamedValue[] lEnvironment = null;
      com.sun.star.beans.NamedValue[] lDispatchArgs = null;
 
      int c = lArgs.length;
      for (int i=0; i<c; ++i) {
          if (lArgs[i].Name.equals("Config"))
              lGenericConfig = (com.sun.star.beans.NamedValue[])
                  com.sun.star.uno.AnyConverter.toArray(lArgs[i].Value);
              else
                  if (lArgs[i].Name.equals("JobConfig"))
                      lJobConfig = (com.sun.star.beans.NamedValue[]) com.sun.star.uno.AnyConverter.toArray(lArgs[i].Value);
              else
                  if (lArgs[i].Name.equals("Environment"))
                      lEnvironment = (com.sun.star.beans.NamedValue[]) com.sun.star.uno.AnyConverter.toArray(lArgs[i].Value);
              else
                  if (lArgs[i].Name.equals("DynamicData"))
                      lDispatchArgs = (com.sun.star.beans.NamedValue[]) com.sun.star.uno.AnyConverter.toArray(lArgs[i].Value);
              else
                  // It is not realy an error - because unknown items can be ignored ...
                  throw new com.sun.star.lang.IllegalArgumentException("unknown sub list detected");
      }
 
      // Analyze the environment info. This sub list is the only guarenteed one!
      if (lEnvironment==null)
          throw new com.sun.star.lang.IllegalArgumentException("no environment");
 
      java.lang.String sEnvType = null;
      java.lang.String sEventName = null;
      com.sun.star.frame.XFrame xFrame = null; com.sun.star.frame.XModel xModel = null;
 
      c = lEnvironment.length;
      for (int i=0; i<c; ++i) {
          if (lEnvironment[i].Name.equals("EnvType"))
              sEnvType = com.sun.star.uno.AnyConverter.toString(lEnvironment[i].Value);
          else
              if (lEnvironment[i].Name.equals("EventName"))
                  sEventName = com.sun.star.uno.AnyConverter.toString(lEnvironment[i].Value);
              else
                  if (lEnvironment[i].Name.equals("Frame"))
                      xFrame = (com.sun.star.frame.XFrame)com.sun.star.uno.AnyConverter.toObject(
                          new com.sun.star.uno.Type(com.sun.star.frame.XFrame.class), lEnvironment[i].Value); 
              else
                  if (lEnvironment[i].Name.equals("Model"))
                      xModel = (com.sun.star.frame.XModel)com.sun.star.uno.AnyConverter.toObject( 
                          new com.sun.star.uno.Type(com.sun.star.frame.XModel.class), 
                                    lEnvironment[i].Value); 
      }
 
      // Further the environment property "EnvType" is required as minimum.
      if (
          (sEnvType==null) ||
          (
          (!sEnvType.equals("EXECUTOR" )) &&
          (!sEnvType.equals("DISPATCH" )) &&
          (!sEnvType.equals("DOCUMENTEVENT"))
          )
         )
      {
          throw new com.sun.star.lang.IllegalArgumentException("no valid value for EnvType");
      }
 
      // Analyze the set of shared config data.
      java.lang.String sAlias = null;
      if (lGenericConfig!=null) {
          c = lGenericConfig.length;
          for (int i=0; i<c; ++i) {
              if (lGenericConfig[i].Name.equals("Alias"))
                  sAlias = com.sun.star.uno.AnyConverter.toString(lGenericConfig[i].Value);
          }
      }
  }
Content on this page is licensed under the Public Documentation License (PDL).
Personal tools
In other languages