modules/meep-swm/src/main/java/javax/microedition/swm/TaskManager.java

   1 // -*- Mode: Java; indent-tabs-mode: t; tab-width: 4 -*-
   2 // ---------------------------------------------------------------------------
   3 // SquirrelJME
   4 //     Copyright (C) Stephanie Gawroriski <xer@multiphasicapps.net>
   5 // ---------------------------------------------------------------------------
   6 // SquirrelJME is under the Mozilla Public License Version 2.0.
   7 // See license.mkd for licensing and copyright information.
   8 // ---------------------------------------------------------------------------
   9
  10 package javax.microedition.swm;
  11
  12 import cc.squirreljme.runtime.cldc.annotation.Api;
  13 import java.util.List;
  14
  15 /**
  16  * This is an interface which is used to manage tasks. Tasks allow multiple
  17  * suites to be ran at the same time.
  18  *
  19  * @see ManagerFactory
  20  * @since 2016/06/24
  21  */
  22 @SuppressWarnings("InterfaceWithOnlyOneDirectInheritor")
  23 @Api
  24 public interface TaskManager
  25 {
  26         /**
  27          * Adds the given task listener so that if the state of any task changes
  28          * then the provided methods are called.
  29          *
  30          * @param __tl The listener for events.
  31          * @since 2016/06/24
  32          */
  33         @Api
  34         void addTaskListener(TaskListener __tl);
  35
  36         /**
  37          * Returns the task which belongs to the caller of this method.
  38          *
  39          * @return The task of the current caller.
  40          * @since 2016/06/24
  41          */
  42         @Api
  43         Task getCurrentTask();
  44
  45         /**
  46          * This returns the list of all running tasks on the system.
  47          *
  48          * @param __incsys If {@code true} then any tasks which are owned by the
  49          * system are also returned.
  50          * @return The list of tasks which currently exist within the virtual
  51          * machine.
  52          * @since 2016/06/24
  53          */
  54         @Api
  55         List<Task> getTaskList(boolean __incsys);
  56
  57         /**
  58          * Removes the given task listener so that it is no longer notified when
  59          * the state of a task has changed.
  60          *
  61          * @param __tl The task listener to remove.
  62          * @since 2016/06/24
  63          */
  64         @Api
  65         void removeTaskListener(TaskListener __tl);
  66
  67         /**
  68          * Sets the given task so that it appears at the foreground task which
  69          * is running, this operation may fail.
  70          *
  71          * A task that is in the foreground is one which is visible and has
  72          * input focus. It is possible that a call of this method will have no
  73          * effect.
  74          *
  75          * @param __t The task to bring to the foreground.
  76          * @return If {@code true} then the task was brought to the foreground.
  77          * @throws IllegalArgumentException If the task is a system task.
  78          * @since 2016/06/24
  79          */
  80         @Api
  81         boolean setForeground(Task __t)
  82                 throws IllegalArgumentException;
  83
  84         /**
  85          * Attempts to set the priority of a given task. A call of this method
  86          * may affect the amount of time slices which are available to a process
  87          * or its resume priority in the event of cooperative multi-tasking.
  88          *
  89          * @param __t The task to change the priority of.
  90          * @param __p The new priority of the given task.
  91          * @return {@code true} if the priority of the given task has been
  92          * changed.
  93          * @throws IllegalArgumentException if the task is a system task.
  94          * @since 2016/06/24
  95          */
  96         @Api
  97         boolean setPriority(Task __t, TaskPriority __p)
  98                 throws IllegalArgumentException;
  99
 100         /**
 101          * Attempts to create a task which runs the given suite.
 102          *
 103          * The task is created and is initially in the {@link TaskStatus#STARTING}
 104          * state. If starting fails then it enters the
 105          * {@link TaskStatus#START_FAILED} state.
 106          *
 107          * A suite may only be active once and cannot have multiple copies running
 108          * at the same time. In the event that an application is already running it
 109          * must be sent an event specifying an application re-launch.
 110          *
 111          * @param __s The suite to start, must be an application.
 112          * @param __cn The class which extends
 113          * {@link javax.microedition.midlet.MIDlet} and acts as the main entry
 114          * point for the program.
 115          * @return The task which was created.
 116          * @throws IllegalArgumentException If the suite is a library, the given
 117          * class does not exist, or the given class does not extend
 118          * {@link javax.microedition.midlet.MIDlet}.
 119          * @throws IllegalStateException If the suite has been removed.
 120          * @throws NullPointerException On null arguments.
 121          * @since 2016/06/24
 122          */
 123         @Api
 124         Task startTask(Suite __s, String __cn)
 125                 throws IllegalArgumentException, IllegalStateException,
 126                         NullPointerException;
 127
 128         /**
 129          * Attempts to stop the given task and destroy it so that it does not
 130          * consume memory or execution cycles.
 131          *
 132          * @param __t The task to be stopped.
 133          * @return {@code true} if the task has been stopped and destroyed.
 134          * @throws IllegalArgumentException If the task has already stopped, has
 135          * not yet been started, or has finished execution.
 136          * @throws IllegalStateException If the task is a system task.
 137          * @since 2016/06/24
 138          */
 139         @Api
 140         boolean stopTask(Task __t)
 141                 throws IllegalArgumentException, IllegalStateException;
 142 }
 143