com.quinsoft.zeidon.Task Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of zeidon-joe Show documentation
There is a newer version: 2.2.0
/**
    This file is part of the Zeidon Java Object Engine (Zeidon JOE).

    Zeidon JOE is free software: you can redistribute it and/or modify
    it under the terms of the GNU Lesser General Public License as published by
    the Free Software Foundation, either version 3 of the License, or
    (at your option) any later version.

    Zeidon JOE is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU Lesser General Public License for more details.

    You should have received a copy of the GNU Lesser General Public License
    along with Zeidon JOE.  If not, see .

    Copyright 2009-2015 QuinSoft
 */
package com.quinsoft.zeidon;

import java.util.Collection;
import java.util.List;

import com.quinsoft.zeidon.objectdefinition.EntityDef;
import com.quinsoft.zeidon.standardoe.ScalaHelper;


/**
 * 
 * All methods operating on a task.  A task is the basic container for Zeidon Object
 * Instances (OIs). When a task is no longer referenced all of its OIs will be dropped.
 * 
 *
 * 
 * A task is created by the Object Engine and has three main properties:
 * 

 *    
 *    Default application: when calling methods that take a LOD name then the LOD is
 *            retrieved from the default application.  (Some methods allow for a
 *            different application to be specified.)
 *    
 *    
 *    Task ID: A unique string that can be used to retrieve the task from the OE.  If
 *            the ID is not specified when the task is created it will default to a
 *            unique integer.
 *    
 *    
 *    Persistent: It a task is persistent then the ObjectEngine will keep an internal
 *            reference to the task to prevent the task from being garbage-collected.
 *            By default tasks are NOT persistent.
 *    
 * 

 *
 * Tasks are usually created like:
 * 
 *      Task task = objectEngine.createTask( "DefaultApplication" );
 * 
 *
 */
public interface Task extends TaskQualification
{
    /**
     * Get the list of views for this task.  Includes views without names.  Use this
     * method carefully.  It is possible to create a memory leak by holding on to
     * the list that is returned.
     *
     * @return list of views for this task.
     */
    Collection getViewList();

    /**
     * Returns an approximate count of views for this task.  It is approximate because
     * the GC may not have cleaned up some views.
     *
     * @return view count
     */
    int getViewCount();

    /**
     * Get a string ID that uniquely defines this task.  Is not restricted to digits.
     *
     * @return task ID
     */
    String getTaskId();

    /**
     * @deprecated
     */
    @Deprecated
    String getUserId();

    /**
     * @deprecated
     */
    @Deprecated
    void setUserId( String userId );

    /**
     * If the task is persistent, this makes it non-persistent.  The task will then
     * be cleaned up when there are no longer any references to the task.  This DOES NOT
     * explicitly drop the task.
     */
    void dropTask();

    /**
     * If false then dropTask() has been called on this task.
     * @return
     */
    boolean isValid();

    /**
     * Commit the list of view in a single transaction.  If the commit fails for one
     * view then it fails for all of them.
     *
     * @param views list of views to commit.
     *
     * @return 0
     */
    int commitMultipleOis( View...views );

    /**
     * Commit the list of view in a single transaction.  If the commit fails for one
     * view then it fails for all of them.
     *
     * @param views list of views to commit.
     *
     * @return 0
     */
    int commitMultipleOis( CommitOptions options, View...views );

    /**
     * Commit the list of view in a single transaction.  If the commit fails for one
     * view then it fails for all of them.
     *
     * @param views list of views to commit.
     *
     * @return 0
     */
    int commitMultipleOis( Collection views );

    /**
     * Commit the list of view in a single transaction.  If the commit fails for one
     * view then it fails for all of them.
     *
     * @param views list of views to commit.
     *
     * @return 0
     */
    int commitMultipleOis( CommitOptions options, Collection views );

    /**
     * Drop the name for the specified view.
     *
     * @param name name to drop.
     * @param view view that should have this name.  TODO: is this necessary?
     */
    void dropNameForView( String name, View view );

    /**
     * Return list of names for the specified view.
     *
     * @param view view to find views.
     *
     * @return list of names for the specified view.
     */
    List getViewNameList(View view);

    /**
     * Set the name of the view inside this task.
     *
     * @param name name of the view
     *
     * @param view view to be named.
     */
    void setNameForView( String name, View view );

    /**
     * Sets a description for this task.  This is for debugging purposes only.
     *
     * @param description
     */
    void setDescription( String description );

    /**
     * Gets the description for this task.  This is for debugging purposes only.
     *
     * @return task description
     */
    String getDescription();

    /**
     * Returns a helper object for calling Scala code from the JOE.  Creates one per task.
     *
     * @return a task-specific Scala helper.
     */
    ScalaHelper getScalaHelper();

    /**
     * Gets an entity cache for this task.  If one doesn't exist for this
     * task the system task will be checked.
     *
     * @param entityDef
     * @return
     */
    EntityCache getEntityCache( EntityDef entityDef );

    /**
     * Sets (or replaces) the EntityCache for an entity.
     *
     * @param entityCache
     * @return true if there was already an EntityCache for the entity.
     */
    boolean setEntityCache( EntityCache entityCache);

    void addTaskCleanupWork( DropTaskCleanup work );

    /**
     * Get the CacheMap for the Task.
     */
    public CacheMap getCacheMap();

    /**
     * Returns an OI source selector for the default application of the task.
     */
    public OiSourceSelector getOiSourceSelector();
}