Menu
▾
▴
[Ivc-cvs] SF.net SVN: cishell: [80] trunk/core/org.cishell.framework/src/org/cishell
|
From: <bh...@us...> - 2006-06-30 19:05:32
|
Revision: 80 Author: bh2 Date: 2006-06-30 12:05:13 -0700 (Fri, 30 Jun 2006) ViewCVS: http://svn.sourceforge.net/cishell/?rev=80&view=rev Log Message: ----------- javadocced and updated the cishell api Modified Paths: -------------- trunk/core/org.cishell.framework/src/org/cishell/client/service/modelmanager/ModelManagerAdapter.java trunk/core/org.cishell.framework/src/org/cishell/client/service/modelmanager/ModelManagerListener.java trunk/core/org.cishell.framework/src/org/cishell/client/service/modelmanager/ModelManagerService.java trunk/core/org.cishell.framework/src/org/cishell/client/service/scheduler/SchedulerAdapter.java trunk/core/org.cishell.framework/src/org/cishell/client/service/scheduler/SchedulerListener.java trunk/core/org.cishell.framework/src/org/cishell/client/service/scheduler/SchedulerService.java trunk/core/org.cishell.framework/src/org/cishell/framework/algorithm/Algorithm.java trunk/core/org.cishell.framework/src/org/cishell/framework/algorithm/ProgressMonitor.java trunk/core/org.cishell.framework/src/org/cishell/framework/algorithm/ProgressTrackable.java trunk/core/org.cishell.framework/src/org/cishell/framework/algorithm/package.html trunk/core/org.cishell.framework/src/org/cishell/framework/datamodel/BasicDataModel.java trunk/core/org.cishell.framework/src/org/cishell/framework/datamodel/DataModel.java trunk/core/org.cishell.framework/src/org/cishell/framework/datamodel/DataModelProperty.java trunk/core/org.cishell.framework/src/org/cishell/framework/datamodel/DataModelType.java trunk/core/org.cishell.framework/src/org/cishell/service/conversion/DataConversionService.java trunk/core/org.cishell.framework/src/org/cishell/service/guibuilder/GUI.java trunk/core/org.cishell.framework/src/org/cishell/service/guibuilder/GUIBuilderService.java trunk/core/org.cishell.framework/src/org/cishell/service/guibuilder/SelectionListener.java Added Paths: ----------- trunk/core/org.cishell.framework/src/org/cishell/client/service/modelmanager/package.html trunk/core/org.cishell.framework/src/org/cishell/client/service/scheduler/package.html trunk/core/org.cishell.framework/src/org/cishell/framework/datamodel/package.html trunk/core/org.cishell.framework/src/org/cishell/framework/doc-files/ trunk/core/org.cishell.framework/src/org/cishell/framework/doc-files/cishell-logo-400.png trunk/core/org.cishell.framework/src/org/cishell/framework/package.html trunk/core/org.cishell.framework/src/org/cishell/overview.html trunk/core/org.cishell.framework/src/org/cishell/service/conversion/package.html trunk/core/org.cishell.framework/src/org/cishell/service/guibuilder/package.html Modified: trunk/core/org.cishell.framework/src/org/cishell/client/service/modelmanager/ModelManagerAdapter.java =================================================================== --- trunk/core/org.cishell.framework/src/org/cishell/client/service/modelmanager/ModelManagerAdapter.java 2006-06-29 20:56:29 UTC (rev 79) +++ trunk/core/org.cishell.framework/src/org/cishell/client/service/modelmanager/ModelManagerAdapter.java 2006-06-30 19:05:13 UTC (rev 80) @@ -16,10 +16,13 @@ import org.cishell.framework.datamodel.DataModel; /** + * An abstract adapter class for notification of changes in the + * {@link ModelManagerService}. The methods in this class are empty. This class + * exists as a convenience for creating listener objects. * - * @author + * @author Bruce Herr (bh...@bh...) */ -public class ModelManagerAdapter implements ModelManagerListener { +public abstract class ModelManagerAdapter implements ModelManagerListener { /** * @see org.cishell.client.service.modelmanager.ModelManagerListener#modelAdded(org.cishell.framework.datamodel.DataModel) */ Modified: trunk/core/org.cishell.framework/src/org/cishell/client/service/modelmanager/ModelManagerListener.java =================================================================== --- trunk/core/org.cishell.framework/src/org/cishell/client/service/modelmanager/ModelManagerListener.java 2006-06-29 20:56:29 UTC (rev 79) +++ trunk/core/org.cishell.framework/src/org/cishell/client/service/modelmanager/ModelManagerListener.java 2006-06-30 19:05:13 UTC (rev 80) @@ -16,8 +16,34 @@ import org.cishell.framework.datamodel.DataModel; +/** + * A listener that is notified of changes in the {@link ModelManagerService}. + * + * @author Bruce Herr (bh...@bh...) + */ public interface ModelManagerListener { + + /** + * Notifies that a model has been added to the associated + * {@link ModelManagerService} + * + * @param dm The added {@link DataModel} + */ public void modelAdded(DataModel dm); + + /** + * Notifies that a model has been removed from the associated + * {@link ModelManagerService} + * + * @param dm The removed {@link DataModel} + */ public void modelRemoved(DataModel dm); + + /** + * Notifies that a set of models have been selected in the associated + * {@link ModelManagerService} + * + * @param dm The selected {@link DataModel}s + */ public void modelsSelected(DataModel[] dm); } Modified: trunk/core/org.cishell.framework/src/org/cishell/client/service/modelmanager/ModelManagerService.java =================================================================== --- trunk/core/org.cishell.framework/src/org/cishell/client/service/modelmanager/ModelManagerService.java 2006-06-29 20:56:29 UTC (rev 79) +++ trunk/core/org.cishell.framework/src/org/cishell/client/service/modelmanager/ModelManagerService.java 2006-06-30 19:05:13 UTC (rev 80) @@ -9,20 +9,75 @@ * Created on Jun 14, 2006 at Indiana University. * * Contributors: - * Indiana University - + * Indiana University - Initial API * ***************************************************************************/ package org.cishell.client.service.modelmanager; import org.cishell.framework.datamodel.DataModel; +/** + * A service for managing loaded {@link DataModel}s. + * {@link ModelManagerListener}s may be registered to be notified of changes + * in the model manager. + * + * Clients are encouraged to use this service for managing the models they have + * loaded into memory. Algorithm writers are encouraged not to use this service + * as it is not guaranteed to be available like the standard CIShell services + * are. + * + * @author Bruce Herr (bh...@bh...) + */ public interface ModelManagerService { + /** + * Adds a DataModel to the manager + * + * @param model The data model + */ public void addModel(DataModel model); + + /** + * Removes a DataModel from the manager + * + * @param model The data model + */ public void removeModel(DataModel model); + + /** + * Sets which data models are selected in the manager. If a given DataModel + * in the array of DataModels is not in the model manager, then it will be + * automatically added before selection. + * + * @param models The data models to select + */ public void setSelectedModels(DataModel[] models); + /** + * Returns the models that have been selected in the manager + * + * @return An array of DataModels, length may be zero + */ public DataModel[] getSelectedModels(); - public DataModel[] getModels(); + /** + * Returns all of the DataModels loaded into the manager + * + * @return An array of DataModels, length may be zero + */ + public DataModel[] getAllModels(); + + /** + * Adds a {@link ModelManagerListener} that will be notified as DataModels + * are added, removed, and selected + * + * @param listener The listener to be notified of events + */ public void addModelManagerListener(ModelManagerListener listener); + + /** + * Removes the {@link ModelManagerListener} from the listener group and will + * no longer notify it of events + * + * @param listener The listener to be removed + */ public void removeModelManagerListener(ModelManagerListener listener); } Added: trunk/core/org.cishell.framework/src/org/cishell/client/service/modelmanager/package.html =================================================================== --- trunk/core/org.cishell.framework/src/org/cishell/client/service/modelmanager/package.html (rev 0) +++ trunk/core/org.cishell.framework/src/org/cishell/client/service/modelmanager/package.html 2006-06-30 19:05:13 UTC (rev 80) @@ -0,0 +1,27 @@ +<!doctype html public "-//w3c//dtd html 4.0 transitional//en"> +<html> +<head> + <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> + <title>org.cishell.framework.datamodel Package-level Javadoc</title> +<!-- +/* **************************************************************************** + * CIShell: Cyberinfrastructure Shell, An Algorithm Integration Framework. + * + * All rights reserved. This program and the accompanying materials are made + * available under the terms of the Apache License v2.0 which accompanies + * this distribution, and is available at: + * http://www.apache.org/licenses/LICENSE-2.0.html + * + * Created on Jun 30, 2006 at Indiana University. + * + * Contributors: + * Indiana University - Initial API Documentation + * ***************************************************************************/ +--> +</head> +<body>Provides the specification for the CIShell model manager service +<h2>Package Specification</h2> +This package specifies the API related to the model manager service. + +</body> +</html> \ No newline at end of file Modified: trunk/core/org.cishell.framework/src/org/cishell/client/service/scheduler/SchedulerAdapter.java =================================================================== --- trunk/core/org.cishell.framework/src/org/cishell/client/service/scheduler/SchedulerAdapter.java 2006-06-29 20:56:29 UTC (rev 79) +++ trunk/core/org.cishell.framework/src/org/cishell/client/service/scheduler/SchedulerAdapter.java 2006-06-30 19:05:13 UTC (rev 80) @@ -9,7 +9,7 @@ * Created on Jun 14, 2006 at Indiana University. * * Contributors: - * Indiana University - + * Indiana University - Initial API * ***************************************************************************/ package org.cishell.client.service.scheduler; @@ -18,6 +18,13 @@ import org.cishell.framework.algorithm.Algorithm; import org.cishell.framework.datamodel.DataModel; +/** + * An abstract adapter class for notification of events happening in a + * {@link SchedulerService}. The methods in this class are empty. This class + * exists as a convenience for creating listener objects. + * + * @author Bruce Herr (bh...@bh...) + */ public class SchedulerAdapter implements SchedulerListener { public void algorithmError(Algorithm algorithm, Exception error) { } Modified: trunk/core/org.cishell.framework/src/org/cishell/client/service/scheduler/SchedulerListener.java =================================================================== --- trunk/core/org.cishell.framework/src/org/cishell/client/service/scheduler/SchedulerListener.java 2006-06-29 20:56:29 UTC (rev 79) +++ trunk/core/org.cishell.framework/src/org/cishell/client/service/scheduler/SchedulerListener.java 2006-06-30 19:05:13 UTC (rev 80) @@ -9,7 +9,7 @@ * Created on Jun 14, 2006 at Indiana University. * * Contributors: - * Indiana University - + * Indiana University - Initial API * ***************************************************************************/ package org.cishell.client.service.scheduler; @@ -19,13 +19,66 @@ import org.cishell.framework.datamodel.DataModel; +/** + * A listener that is notified of events happening in a {@link SchedulerService} + * + * @author Bruce Herr (bh...@bh...) + */ public interface SchedulerListener { + /** + * Notification that an Algorithm has been scheduled to be run at a certain + * time + * + * @param algorithm The scheduled Algorithm + * @param time The time is scheduled to be run + */ public void algorithmScheduled(Algorithm algorithm, Calendar time); + + /** + * Notification that an already scheduled Algorithm has been rescheduled + * to be run at a different time + * + * @param algorithm The scheduled Algorithm + * @param time The new time the Algorithm is scheduled to be run + */ public void algorithmRescheduled(Algorithm algorithm, Calendar time); + + /** + * Notification that an Algorithm has started execution + * + * @param algorithm The scheduled algorithm + */ public void algorithmStarted(Algorithm algorithm); + + /** + * Notification that an Algorithm has finished executing + * + * @param algorithm The scheduled Algorithm + * @param createdDM The DataModel(s) it returned, or <code>null</code> if + * it returned <code>null</code> + */ public void algorithmFinished(Algorithm algorithm, DataModel[] createdDM); + + /** + * Notification that an Algorithm had an error while being executed + * + * @param algorithm The scheduled Algorithm + * @param error The error it threw while executing + */ public void algorithmError(Algorithm algorithm, Exception error); + /** + * Notification that the scheduler's run state (paused or unpaused) has + * changed + * + * @param isRunning <code>true</code> if it is now running, + * <code>false</code> if it is no longer running (paused) + */ public void schedulerRunStateChanged(boolean isRunning); + + /** + * Notification that the scheduler's schedule of Algorithms to be run has + * been cleared. + */ public void schedulerCleared(); } Modified: trunk/core/org.cishell.framework/src/org/cishell/client/service/scheduler/SchedulerService.java =================================================================== --- trunk/core/org.cishell.framework/src/org/cishell/client/service/scheduler/SchedulerService.java 2006-06-29 20:56:29 UTC (rev 79) +++ trunk/core/org.cishell.framework/src/org/cishell/client/service/scheduler/SchedulerService.java 2006-06-30 19:05:13 UTC (rev 80) @@ -9,28 +9,141 @@ * Created on Jun 14, 2006 at Indiana University. * * Contributors: - * Indiana University - + * Indiana University - Initial API * ***************************************************************************/ package org.cishell.client.service.scheduler; import java.util.Calendar; -import java.util.Map; import org.cishell.framework.algorithm.Algorithm; + +/** + * A service for scheduling {@link Algorithm}s to be run. + * {@link SchedulerListener}s may be registered to be notified of events. + * + * Clients are encouraged to use this service for scheduling Algorithms to be + * run. Algorithm writers are encouraged not to use this service as it is not + * guaranteed to be available like the standard CIShell services are. + * + * @author Bruce Herr (bh...@bh...) + */ public interface SchedulerService { + /** + * Schedules an Algorithm to be run immediately. If there are simply not + * enough resources to run it, it will still have to wait until there are + * enough resources to fulfill the request. + * + * @param algorithm The algorithm to be run + */ public void runNow(Algorithm algorithm); + + /** + * Schedules an Algorithm to be run when convenient. This schedules an + * Algorithm to be run now, but gives no urgent priority to it. Most + * Algorithms will be scheduled in this way. + * + * @param algorithm The Algorithm to be scheduled + */ public void schedule(Algorithm algorithm); + + /** + * Schedules an Algorithm to be run at a specific time. The Algorithm will + * be run at the given time unless there is simply not enough resources + * at that time. In which case it would wait until there are enough + * resources to fulfill the request. + * + * @param algorithm The Algorithm to be scheduled + * @param time What time this Algorithm should be run + */ public void schedule(Algorithm algorithm, Calendar time); + + /** + * Reschedules an already scheduled Algorithm to be run at a different time. + * If the Algorithm is not scheduled already, then this method will have no + * effect and will return <code>false</code>. + * + * @param algorithm The Algorithm already scheduled + * @param newTime The revised time in which to run the Algorithm + * @return If the Algorithm was successfully rescheduled + */ public boolean reschedule(Algorithm algorithm, Calendar newTime); + + /** + * Unschedules an already scheduled, but not running Algorithm from the + * scheduler. Tries to unschedule an Algorithm from the scheduler. If the + * Algorithm isn't in the scheduler or if the Algorithm is already running + * then this method returns <code>false</code>. + * + * @param algorithm The Algorithm to remove from the scheduler + * @return If the Algorithm was successfully unscheduled + */ public boolean unschedule(Algorithm algorithm); + /** + * Adds a listener to be notified of events happening in the scheduler. + * + * @param listener The listener to be added + */ public void addSchedulerListener(SchedulerListener listener); + + /** + * Removes a {@link SchedulerListener} from the group of listeners listening + * for scheduler events. This method has no effect if the listener isn't + * in the group of listeners. + * + * @param listener The listener to be removed + */ public void removeSchedulerListener(SchedulerListener listener); + + /** + * Returns whether the scheduler is running + * + * @return if the scheduler is running + */ + public boolean isRunning(); - public boolean isRunning(); - public void setRunning(boolean running); - public Map getSchedule(); + /** + * Pauses or unpauses the running of new {@link Algorithm}s in the + * scheduler + * + * @param isRunning <code>true</code> to pause, + * <code>false</code> to unpause + */ + public void setRunning(boolean isRunning); + + /** + * Returns an array of {@link Algorithm}s that the scheduler has scheduled. + * This includes the Algorithms that are currently running and the ones + * queued to be run. This also just gives a snapshot of the current set of + * scheduled Algorithms, so it is not guaranteed to be accurate even + * directly after the method returns. + * + * @return The set of Algorithms currently scheduled in the scheduler + */ + public Algorithm[] getScheduledAlgorithms(); + + /** + * Returns the time in which a scheduled Algorithm is scheduled to be run. + * The time may be in the past if the Algorithm is already running or + * <code>null</code> if the Algorithm is not scheduled. + * + * @param algorithm The Algorithm + * @return The scheduled time for the Algorithm to run or <code>null</code> + * if the Algorithm is not scheduled or has completed execution. + */ + public Calendar getScheduledTime(Algorithm algorithm); + + /** + * Clears all currently scheduled Algorithms to be run. If an Algorithm is + * already running, then it will continue to run until finished. + */ public void clearSchedule(); + + /** + * Returns if there are any Algorithms scheduled + * + * @return Whether there are any Algorithms scheduled + */ public boolean isEmpty(); } Added: trunk/core/org.cishell.framework/src/org/cishell/client/service/scheduler/package.html =================================================================== --- trunk/core/org.cishell.framework/src/org/cishell/client/service/scheduler/package.html (rev 0) +++ trunk/core/org.cishell.framework/src/org/cishell/client/service/scheduler/package.html 2006-06-30 19:05:13 UTC (rev 80) @@ -0,0 +1,27 @@ +<!doctype html public "-//w3c//dtd html 4.0 transitional//en"> +<html> +<head> + <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> + <title>org.cishell.framework.datamodel Package-level Javadoc</title> +<!-- +/* **************************************************************************** + * CIShell: Cyberinfrastructure Shell, An Algorithm Integration Framework. + * + * All rights reserved. This program and the accompanying materials are made + * available under the terms of the Apache License v2.0 which accompanies + * this distribution, and is available at: + * http://www.apache.org/licenses/LICENSE-2.0.html + * + * Created on Jun 30, 2006 at Indiana University. + * + * Contributors: + * Indiana University - Initial API Documentation + * ***************************************************************************/ +--> +</head> +<body>Provides the specification for the CIShell scheduler service +<h2>Package Specification</h2> +This package specifies the API related to the scheduler service. + +</body> +</html> \ No newline at end of file Modified: trunk/core/org.cishell.framework/src/org/cishell/framework/algorithm/Algorithm.java =================================================================== --- trunk/core/org.cishell.framework/src/org/cishell/framework/algorithm/Algorithm.java 2006-06-29 20:56:29 UTC (rev 79) +++ trunk/core/org.cishell.framework/src/org/cishell/framework/algorithm/Algorithm.java 2006-06-30 19:05:13 UTC (rev 80) @@ -16,7 +16,7 @@ import org.cishell.framework.datamodel.DataModel; /** - * An algorithm. In CIShell an algorithm can be basically any arbitrary code + * In CIShell, an algorithm can be basically any arbitrary code * execution cycle. What happens when the execute method is run is entirely * up to the Algorithm writer. Some algorithms may be primed with a data model * that it analyzes and returns a derivitive data model or it may convert from Modified: trunk/core/org.cishell.framework/src/org/cishell/framework/algorithm/ProgressMonitor.java =================================================================== --- trunk/core/org.cishell.framework/src/org/cishell/framework/algorithm/ProgressMonitor.java 2006-06-29 20:56:29 UTC (rev 79) +++ trunk/core/org.cishell.framework/src/org/cishell/framework/algorithm/ProgressMonitor.java 2006-06-30 19:05:13 UTC (rev 80) @@ -15,21 +15,60 @@ /** * A class to monitor the progress of an algorithm. It allows for notification - * of progress, notification of cancellation, and description of current work - * during execution. These methods are generally only called by the algorithm - * with the CIShell client providing the progress monitor implementation. + * of progress, notification of cancellation, notification of pausing, and + * description of current work during execution. These methods are generally + * only called by the algorithm with the CIShell client providing the progress + * monitor implementation. * * @author Bruce Herr (bh...@bh...) */ public interface ProgressMonitor { + /** + * A monitor with empty methods for use by algorithms when no + * ProgressMonitor has been given to it. This helps to eliminate spurious + * <code>null</code> checks to ensure the progress monitor is not + * <code>null</code>. + */ + public static final ProgressMonitor NULL_MONITOR = new ProgressMonitor() { + public void describeWork(String currentWork) {} + public void done() {} + public boolean isCanceled() {return false;} + public boolean isPaused() {return false;} + public void setCanceled(boolean value) {} + public void setPaused(boolean value) {} + public void start(int capabilities, int totalWorkUnits) {} + public void worked(int work) {}}; + + /** + * Capability constant specifying that this algorithm can + * update its work progress (value is 1<<1) + */ + public static final int WORK_TRACKABLE = 1 << 1; + + /** + * Capability constant specifying that this algorithm can + * be cancelled (value is 1<<2) + */ + public static final int CANCELLABLE = 1 << 2; + + /** + * Capability constant specifying that this algorithm can + * be paused (value is 1<<3) + */ + public static final int PAUSEABLE = 1 << 3; + /** * Notifies the start of execution of the algorithm in addition to * revealing how many work units will be used. * + * @param capabilities An ORed int that tells the monitor what the + * algorithm is capable of with respect to the + * monitor. The ORed values are taken from the int + * constants specified in this interface. * @param totalWorkUnits The number of work units, may be -1 if the * algorithm does not provide progress information. */ - public void start(int totalWorkUnits); + public void start(int capabilities, int totalWorkUnits); /** * Notifies that a certain number of units of work has been completed @@ -47,10 +86,10 @@ /** * Sets or clears a flag for cancellation of this algorithm's execution. * An algorithm writer can ignore or clear this flag if it cannot stop - * midstream. This is the only method that can be called by someone other - * than the algorithm. + * midstream. This is one of the methods that can be called by someone + * other than the algorithm. * - * @param value Set or clear the cancellation of algorithm execution + * @param value Set or clear the cancellation request */ public void setCanceled(boolean value); @@ -64,6 +103,25 @@ public boolean isCanceled(); /** + * Sets or clears a flag for pausing of this algorithm's execution. An + * algorithm writer can ignore or clear this flag if it cannot pause + * midstream. This is one of the methods that can be called by someone + * other than the algorithm. + * + * @param value Set or clear the pause request + */ + public void setPaused(boolean value); + + /** + * Returns whether pausing of algorithm execution is requested. An + * algorithm that can be paused should poll this method when convenient + * to see if it should pause. + * + * @return Whether pausing of algorithm execution is requested + */ + public boolean isPaused(); + + /** * Method to describe what the algorithm is currently doing for the benefit * of the users of the algorithm as it progresses during execution. * Modified: trunk/core/org.cishell.framework/src/org/cishell/framework/algorithm/ProgressTrackable.java =================================================================== --- trunk/core/org.cishell.framework/src/org/cishell/framework/algorithm/ProgressTrackable.java 2006-06-29 20:56:29 UTC (rev 79) +++ trunk/core/org.cishell.framework/src/org/cishell/framework/algorithm/ProgressTrackable.java 2006-06-30 19:05:13 UTC (rev 80) @@ -35,4 +35,13 @@ * @param monitor The monitor the algorithm is to use */ public void setProgressMonitor(ProgressMonitor monitor); + + /** + * Returns the progress monitor currently in use, or <code>null</code> if + * no monitor has been set. + * + * @return The current progress monitor, or <code>null</code> if there + * isn't one set. + */ + public ProgressMonitor getProgressMonitor(); } Modified: trunk/core/org.cishell.framework/src/org/cishell/framework/algorithm/package.html =================================================================== --- trunk/core/org.cishell.framework/src/org/cishell/framework/algorithm/package.html 2006-06-29 20:56:29 UTC (rev 79) +++ trunk/core/org.cishell.framework/src/org/cishell/framework/algorithm/package.html 2006-06-30 19:05:13 UTC (rev 80) @@ -19,8 +19,7 @@ * ***************************************************************************/ --> </head> -<body> -Provides interfaces required for creating CIShell compatible algorithms +<body>Provides interfaces required for creating CIShell compatible algorithms <h2>Package Specification</h2> This package specifies the API related to creation of CIShell compatible algorithms. Modified: trunk/core/org.cishell.framework/src/org/cishell/framework/datamodel/BasicDataModel.java =================================================================== --- trunk/core/org.cishell.framework/src/org/cishell/framework/datamodel/BasicDataModel.java 2006-06-29 20:56:29 UTC (rev 79) +++ trunk/core/org.cishell.framework/src/org/cishell/framework/datamodel/BasicDataModel.java 2006-06-30 19:05:13 UTC (rev 80) @@ -16,15 +16,33 @@ import java.util.Dictionary; import java.util.Hashtable; - +/** + * A basic implementation of {@link DataModel}. This class was included since + * a simple implementation of DataModel will be used quite often in both client + * and algorithm code. + * + * @author Bruce Herr (bh...@bh...) + */ public class BasicDataModel implements DataModel { private Dictionary properties; private Object data; + /** + * Creates a DataModel with the given data and an empty meta-data + * {@link Dictionary} + * + * @param data The data being wrapped + */ public BasicDataModel(Object data) { this(new Hashtable(), data); } + /** + * Creates a DataModel with the given data and meta-data {@link Dictionary} + * + * @param properties The meta-data about the data + * @param data The data being wrapped + */ public BasicDataModel(Dictionary properties, Object data) { this.properties = properties; this.data = data; Modified: trunk/core/org.cishell.framework/src/org/cishell/framework/datamodel/DataModel.java =================================================================== --- trunk/core/org.cishell.framework/src/org/cishell/framework/datamodel/DataModel.java 2006-06-29 20:56:29 UTC (rev 79) +++ trunk/core/org.cishell.framework/src/org/cishell/framework/datamodel/DataModel.java 2006-06-30 19:05:13 UTC (rev 80) @@ -15,7 +15,31 @@ import java.util.Dictionary; +/** + * A class that encapsulates data and its meta-data. This class is used to pass + * data between algorithms and what algorithms optionally create when executed. + * + * @author Bruce Herr (bh...@bh...) + */ public interface DataModel { + /** + * Returns the meta-data associated with the data stored in this DataModel. + * Some standard keys are in {@link DataModelProperty}. + * + * @return The data's meta-data + */ public Dictionary getProperties(); + + /** + * Returns the data stored in this DataModel. + * + * @return The data (a java object) + */ public Object getData(); + + //TODO: Consider these methods for inclusion in DataModel + //public String getType(); + + //public String getUID(); //may be better for specifying parent datamodels + //public Object getDataAsType(String type); } Modified: trunk/core/org.cishell.framework/src/org/cishell/framework/datamodel/DataModelProperty.java =================================================================== --- trunk/core/org.cishell.framework/src/org/cishell/framework/datamodel/DataModelProperty.java 2006-06-29 20:56:29 UTC (rev 79) +++ trunk/core/org.cishell.framework/src/org/cishell/framework/datamodel/DataModelProperty.java 2006-06-30 19:05:13 UTC (rev 80) @@ -9,36 +9,48 @@ * Created on Jun 15, 2006 at Indiana University. * * Contributors: - * Indiana University - + * Indiana University - Initial API * ***************************************************************************/ package org.cishell.framework.datamodel; - +/** + * Standard property keys to use when creating meta-data for a + * {@link DataModel}. + * + * @author Bruce Herr (bh...@bh...) + */ public interface DataModelProperty { - /** The Label of the DataModel */ + /** + * The label to give the DataModel if displayed. The type associated with + * this property is of type {@link String}. + */ public static final String LABEL = "Label"; /** - * The Parent DataModel of the DataModel. This is used when a model - * is derived from another DataModel, to show the hierarchical relationship - * between them. This Property can be null, signifying that the DataModel + * The parent DataModel of the DataModel. This is used when a DataModel + * is derived from another DataModel to show the hierarchical relationship + * between them. This property can be null, signifying that the DataModel * was not derived from any DataModel, such as when loading a new DataModel - * from a file. - * */ + * from a file. The type associated with this property is of type + * {@link DataModel} + */ public static final String PARENT = "Parent"; + //TODO: should we consider removing this/changing it? /** - * The type of this DataModel. Various standard types are created as - * constants in the DataModelType class. These can be used, or new - * types can be introduced as needed by creating new DataModelTypes. + * The type of the DataModel. Various standard types are created as + * constants in the {@link DataModelType} class. These can be used, or new + * types can be introduced as needed. The type associated with this + * property is of type {@link String}. */ public static final String TYPE = "Type"; /** - * Flag to determined if this DataModel has been modified and not saved since - * the modification. This is used to do things like notify the user before they - * exit that a modified DataModel exists and see if they want to save it. + * Flag to determine if this DataModel has been modified and not saved since + * the modification. This is used to do things like notify the user before + * they exit that a modified DataModel exists and see if they want to save + * it. The type associated with this property is of type {@link Boolean}. */ public static final String MODIFIED = "Modified"; } Modified: trunk/core/org.cishell.framework/src/org/cishell/framework/datamodel/DataModelType.java =================================================================== --- trunk/core/org.cishell.framework/src/org/cishell/framework/datamodel/DataModelType.java 2006-06-29 20:56:29 UTC (rev 79) +++ trunk/core/org.cishell.framework/src/org/cishell/framework/datamodel/DataModelType.java 2006-06-30 19:05:13 UTC (rev 80) @@ -9,51 +9,31 @@ * Created on Jun 15, 2006 at Indiana University. * * Contributors: - * Indiana University - + * Indiana University - Initial API * ***************************************************************************/ package org.cishell.framework.datamodel; - /** - * Defines some standard DataModelTypes to be used in DataModel PropertyMaps - * to declare the type of a DataModel, as well as allows for creation of - * new types when needed. + * Defines some standard data model types to be used in a DataModel's meta-data + * to declare the type of a {@link DataModel}. These are the values associated + * with the {@link DataModelProperty}, DataModelProperty.TYPE. These 'types' are + * more general and are used to help a user to figure out in a broad sense what + * type of data he or she is looking at. * - * @author Team IVC + * @author Bruce Herr (bh...@bh...) */ -public class DataModelType { +public interface DataModelType { - /** Matrix data model */ - public static DataModelType MATRIX = new DataModelType("Matrix"); + /** Says this data model is abstractly a matrix */ + public static String MATRIX = "Matrix"; - /** Network data model */ - public static DataModelType NETWORK = new DataModelType("Network"); + /** Says this data model is abstractly a network */ + public static String NETWORK = "Network"; - /** Tree data model */ - public static DataModelType TREE = new DataModelType("Tree"); + /** Says this data model is abstractly a tree */ + public static String TREE = "Tree"; - /** Unknown data model */ - public static DataModelType OTHER = new DataModelType("Unknown"); - - private String name; - - /** - * Creates a new DataModelType object. - * - * @param name the name of this DataModelType - */ - public DataModelType(String name) { - this.name = name; - } - - /** - * Returns the name of this DataModelType. - * - * @return the name of this DataModelType - */ - public String getName() { - return name; - } - + /** Says this data model is abstractly an unknown type */ + public static String OTHER = "Unknown"; } Added: trunk/core/org.cishell.framework/src/org/cishell/framework/datamodel/package.html =================================================================== --- trunk/core/org.cishell.framework/src/org/cishell/framework/datamodel/package.html (rev 0) +++ trunk/core/org.cishell.framework/src/org/cishell/framework/datamodel/package.html 2006-06-30 19:05:13 UTC (rev 80) @@ -0,0 +1,29 @@ +<!doctype html public "-//w3c//dtd html 4.0 transitional//en"> +<html> +<head> + <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> + <title>org.cishell.framework.datamodel Package-level Javadoc</title> +<!-- +/* **************************************************************************** + * CIShell: Cyberinfrastructure Shell, An Algorithm Integration Framework. + * + * All rights reserved. This program and the accompanying materials are made + * available under the terms of the Apache License v2.0 which accompanies + * this distribution, and is available at: + * http://www.apache.org/licenses/LICENSE-2.0.html + * + * Created on Jun 30, 2006 at Indiana University. + * + * Contributors: + * Indiana University - Initial API Documentation + * ***************************************************************************/ +--> +</head> +<body>Provides interfaces required for creating DataModels +<h2>Package Specification</h2> +This package specifies the API related to creation of DataModels. + +TODO: Describe here what a DataModel is, how it is used, and why it is used. + +</body> +</html> \ No newline at end of file Added: trunk/core/org.cishell.framework/src/org/cishell/framework/doc-files/cishell-logo-400.png =================================================================== (Binary files differ) Property changes on: trunk/core/org.cishell.framework/src/org/cishell/framework/doc-files/cishell-logo-400.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: trunk/core/org.cishell.framework/src/org/cishell/framework/package.html =================================================================== --- trunk/core/org.cishell.framework/src/org/cishell/framework/package.html (rev 0) +++ trunk/core/org.cishell.framework/src/org/cishell/framework/package.html 2006-06-30 19:05:13 UTC (rev 80) @@ -0,0 +1,29 @@ +<!doctype html public "-//w3c//dtd html 4.0 transitional//en"> +<html> +<head> + <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> + <title>org.cishell.framework.algorithm Package-level Javadoc</title> +<!-- +/* **************************************************************************** + * CIShell: Cyberinfrastructure Shell, An Algorithm Integration Framework. + * + * All rights reserved. This program and the accompanying materials are made + * available under the terms of the Apache License v2.0 which accompanies + * this distribution, and is available at: + * http://www.apache.org/licenses/LICENSE-2.0.html + * + * Created on Jun 29, 2006 at Indiana University. + * + * Contributors: + * Indiana University - Initial API Documentation + * ***************************************************************************/ +--> +</head> +<body>The base package of the CIShell framework specification +<h2>Package Specification</h2> +This package is the root package for the CIShell framework specification + +TODO: Talk about the framework and give links. + +</body> +</html> \ No newline at end of file Added: trunk/core/org.cishell.framework/src/org/cishell/overview.html =================================================================== --- trunk/core/org.cishell.framework/src/org/cishell/overview.html (rev 0) +++ trunk/core/org.cishell.framework/src/org/cishell/overview.html 2006-06-30 19:05:13 UTC (rev 80) @@ -0,0 +1,32 @@ +<!doctype html public "-//w3c//dtd html 4.0 transitional//en"> +<html> +<head> + <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> + <title>org.cishell.framework.algorithm Package-level Javadoc</title> +<!-- +/* **************************************************************************** + * CIShell: Cyberinfrastructure Shell, An Algorithm Integration Framework. + * + * All rights reserved. This program and the accompanying materials are made + * available under the terms of the Apache License v2.0 which accompanies + * this distribution, and is available at: + * http://www.apache.org/licenses/LICENSE-2.0.html + * + * Created on Jun 29, 2006 at Indiana University. + * + * Contributors: + * Indiana University - Initial API Documentation + * ***************************************************************************/ +--> +</head> +<body> +This document is the API specification for the CIShell specification. + +@see <a href="http://www.osgi.org/osgi_technology/download_specs.asp">OSGi +Service Platform Specification, Release 4</a> +@see <a href="http://bundles.osgi.org/javadoc/r4/">OSGi Service Platform, +Release 4 API</a> +@see "The CIShell Specification Paper" + +</body> +</html> \ No newline at end of file Modified: trunk/core/org.cishell.framework/src/org/cishell/service/conversion/DataConversionService.java =================================================================== --- trunk/core/org.cishell.framework/src/org/cishell/service/conversion/DataConversionService.java 2006-06-29 20:56:29 UTC (rev 79) +++ trunk/core/org.cishell.framework/src/org/cishell/service/conversion/DataConversionService.java 2006-06-30 19:05:13 UTC (rev 80) @@ -9,14 +9,77 @@ * Created on Jun 14, 2006 at Indiana University. * * Contributors: - * Indiana University - + * Indiana University - Initial API * ***************************************************************************/ package org.cishell.service.conversion; import org.cishell.framework.algorithm.AlgorithmFactory; +import org.cishell.framework.datamodel.DataModel; +/** + * A service for converting data to different formats. This service should + * utilize the pool of {@link AlgorithmFactory} services which have registered + * with the OSGi service registry and specified in its service dictionary that + * they are a converter. A converter will specify what data format it takes in + * ('in_data'), what it converts it to ('out_data'), and whether any information + * will be lost in the conversion ('consersion'='lossless'|'lossy'). Using this + * and other standard algorithm properties, a DataConversionService will try and + * find the fastest, most efficient way to convert from a one format to another. + * + * @author Bruce Herr (bh...@bh...) + */ public interface DataConversionService { + + /** + * Finds a converter from one format to another if at all possible. The + * returned {@link AlgorithmFactory}, which may be a composite of multiple + * algorithms, will take a {@link DataModel} of the specified + * <code>inFormat</code> and convert it to a DataModel of type + * <code>outFormat</code>. If there is no way to convert the data model, + * <code>null</code> will be returned. + * + * @param inFormat The type of data model to be converted. This String + * should be formatted in the same way as an algorithm's + * {@link AlgorithmProperty#IN_DATA 'in_data'}. + * @param outFormat The type of data model that should be produced. This + * String should be formatted in the same way as an + * algorithm's + * {@link AlgorithmProperty#OUT_DATA 'out_data'}. + * @return An AlgorithmFactory that will convert a data model of the given + * inFormat to the given outFormat, or <code>null</code> if there is + * no way to convert. + */ public AlgorithmFactory converterFor(String inFormat, String outFormat); + + /** + * Finds a converter from one format to another falling within the given + * parameters. The max number of converters to use (maxHops) and the + * maximum allowed complexity for the converters to limit the impact a + * conversion will make. The returned {@link AlgorithmFactory}, which may + * be a composite of multiple algorithms, will take a {@link DataModel} of + * the specified <code>inFormat</code> and convert it to a DataModel of type + * <code>outFormat</code>. If there is no way to convert the data model + * within the given parameters, <code>null</code> will be returned. + * + * @param inFormat The type of data model to be converted. This String + * should be formatted in the same way as an algorithm's + * {@link AlgorithmProperty#IN_DATA 'in_data'}. + * @param outFormat The type of data model that should be produced. This + * String should be formatted in the same way as an + * algorithm's + * {@link AlgorithmProperty#OUT_DATA 'out_data'}. + * @param maxHops The maximum number of converters to use for the + * conversion. + * @param maxComplexity The maximum complexity the conversion algorithm can + * have in order to be considered for use in the + * conversion. The format of the String is in big-O + * notation. Examples are 'O(n)', 'O(n^2)', 'O(log(n))'. + * @return An AlgorithmFactory that will convert a data model of the given + * inFormat to the given outFormat, or <code>null</code> if there is + * no way to convert within the given parameters. + */ public AlgorithmFactory converterFor(String inFormat, String outFormat, int maxHops, String maxComplexity); + + //TODO: More methods of conversion here? } Added: trunk/core/org.cishell.framework/src/org/cishell/service/conversion/package.html =================================================================== --- trunk/core/org.cishell.framework/src/org/cishell/service/conversion/package.html (rev 0) +++ trunk/core/org.cishell.framework/src/org/cishell/service/conversion/package.html 2006-06-30 19:05:13 UTC (rev 80) @@ -0,0 +1,27 @@ +<!doctype html public "-//w3c//dtd html 4.0 transitional//en"> +<html> +<head> + <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> + <title>org.cishell.framework.datamodel Package-level Javadoc</title> +<!-- +/* **************************************************************************** + * CIShell: Cyberinfrastructure Shell, An Algorithm Integration Framework. + * + * All rights reserved. This program and the accompanying materials are made + * available under the terms of the Apache License v2.0 which accompanies + * this distribution, and is available at: + * http://www.apache.org/licenses/LICENSE-2.0.html + * + * Created on Jun 30, 2006 at Indiana University. + * + * Contributors: + * Indiana University - Initial API Documentation + * ***************************************************************************/ +--> +</head> +<body>Provides the specification for the CIShell data conversion service +<h2>Package Specification</h2> +This package specifies the API related to the data conversion service. + +</body> +</html> \ No newline at end of file Modified: trunk/core/org.cishell.framework/src/org/cishell/service/guibuilder/GUI.java =================================================================== --- trunk/core/org.cishell.framework/src/org/cishell/service/guibuilder/GUI.java 2006-06-29 20:56:29 UTC (rev 79) +++ trunk/core/org.cishell.framework/src/org/cishell/service/guibuilder/GUI.java 2006-06-30 19:05:13 UTC (rev 80) @@ -9,16 +9,52 @@ * Created on Jun 14, 2006 at Indiana University. * * Contributors: - * Indiana University - + * Indiana University - Initial API * ***************************************************************************/ package org.cishell.service.guibuilder; import java.util.Dictionary; +/** + * A simple GUI for user interaction. A single {@link SelectionListener} can be + * set to be informed when the user enters information and hits Ok. + * + * @author Bruce Herr (bh...@bh...) + */ public interface GUI { + /** + * Pops up this GUI, gets data from the user, and returns what they entered. + * This is a convenience method that first opens the GUI, then pops the GUI + * up to the user, who then enters in the needed information, which is then + * taken and put into a {@link Dictionary}, and is given to this method's + * caller. + * + * @return The data the user entered or <code>null</code> if they cancelled + * the operation. + */ public Dictionary openAndWait(); + /** + * Opens the GUI and shows it to the user + */ public void open(); + + /** + * Closes the GUI + */ public void close(); + + /** + * Returns if the GUI is closed + * @return If the GUI has been closed or not + */ + public boolean isClosed(); + + /** + * Sets the selection listener to be informed when the user finishes + * entering information and hits 'Ok' or cancels. + * + * @param listener The listener to notify + */ public void setSelectionListener(SelectionListener listener); } Modified: trunk/core/org.cishell.framework/src/org/cishell/service/guibuilder/GUIBuilderService.java =================================================================== --- trunk/core/org.cishell.framework/src/org/cishell/service/guibuilder/GUIBuilderService.java 2006-06-29 20:56:29 UTC (rev 79) +++ trunk/core/org.cishell.framework/src/org/cishell/service/guibuilder/GUIBuilderService.java 2006-06-30 19:05:13 UTC (rev 80) @@ -9,18 +9,128 @@ * Created on Jun 14, 2006 at Indiana University. * * Contributors: - * Indiana University - + * Indiana University - Initial API * ***************************************************************************/ package org.cishell.service.guibuilder; import java.util.Dictionary; +import org.osgi.service.log.LogService; import org.osgi.service.metatype.MetaTypeProvider; +import org.osgi.service.metatype.MetaTypeService; +import org.osgi.service.metatype.ObjectClassDefinition; +/** + * A service for creating simple GUIs for user interaction. This service + * provides several methods for popping up dialog boxes to get or give very + * simple information and a more flexible way to create {@link GUI}s using a + * standard OSGi {@link MetaTypeProvider}. The MetaTypeProvider basically lists + * what input is needed (String, Integer, Float, etc...), a description of the + * input, and a way to validate input. There is also an XML format that OSGi + * provides a service ({@link MetaTypeService}) for that will parse the XML into + * a MetaTypeProvider instance. More information about MetaTypeProvider and + * MetaTypeService is available in the OSGi Service Platform Specification, + * Release 4 Service Compendium, Section 105 (pg 129). You can download it at + * <a href="http://www.osgi.org/osgi_technology/download_specs.asp"> + * http://www.osgi.org/osgi_technology/download_specs.asp</a>. + * + * Algorithm writers are encouraged to use this service if they need to get + * additional input from the user rather than creating their own GUI. This is + * to ensure a consistant user input method and so that the GUI can easily be + * routed to the user when running remotely. + * + * @author Bruce Herr (bh...@bh...) + */ public interface GUIBuilderService { + + /** + * Creates a GUI for user interaction + * + * @param id The id to use to get the correct + * {@link ObjectClassDefinition} from the provided + * MetaTypeProvider + * @param parameters Provides the parameters needed to get information from + * the user + * @return The created GUI + */ public GUI createGUI(String id, MetaTypeProvider parameters); - public GUI createPopup(String popupType); + /** + * Creates a GUI, gets data from the user, and returns what they entered. + * This is a convenience method that first creates a GUI from the provided + * {@link MetaTypeProvider}, then pops the GUI up to the user, who then + * enters in the needed information, which is then taken and put into a + * {@link Dictionary}, and is given to this method's caller. + * + * @param id The id to use to get the correct + * {@link ObjectClassDefinition} from the provided + * MetaTypeProvider + * @param parameters Provides the parameters needed to get information from + * the user + * @return The data the user entered or <code>null</code> if they cancelled + * the operation. + */ public Dictionary createGUIandWait(String id, MetaTypeProvider parameters); - public Dictionary createPopupAndWait(String popupType); + + /** + * Pops up a confirmation box to the user with an 'Ok' and 'Cancel' button + * + * @param title The title of the pop-up + * @param message The message to display + * @param detail Additional details + * @return If they clicked "Ok", <code>true</code>, otherwise + * <code>false</code> + */ + public boolean showConfirm(String title, String message, String detail); + + /** + * Pops up a question box to the user with a 'Yes' and 'No' button + * + * @param title The title of the pop-up + * @param message The question to display + * @param detail Additional details + * @return If they clicked "Yes", <code>true</code>, otherwise + * <code>false</code> + */ + public boolean showQuestion(String title, String message, String detail); + + /** + * Pops up an information box to the user. This should only be used + * sparingly. Algorithms should try to use the {@link LogService} instead. + * + * @param title The title of the pop-up + * @param message The message to display + * @param detail Additional details + */ + public void showInformation(String title, String message, String detail); + + /** + * Pops up a warning box to the user. This should only be used + * sparingly. Algorithms should try to use the {@link LogService} instead. + * + * @param title The title of the pop-up + * @param message The message to display + * @param detail Additional details + */ + public void showWarning(String title, String message, String detail); + + /** + * Pops up an error box to the user. This should only be used + * sparingly. Algorithms should try to use the {@link LogService} instead. + * + * @param title The title of the pop-up + * @param message The message to display + * @param detail Additional details + */ + public void showError(String title, String message, String detail); + + /** + * Pops up an error box to the user. This should only be used + * sparingly. Algorithms should try to use the {@link LogService} instead. + * + * @param title The title of the pop-up + * @param message The message to display + * @param error The actual exception that was thrown + */ + public void showError(String title, String message, Throwable error); } Modified: trunk/core/org.cishell.framework/src/org/cishell/service/guibuilder/SelectionListener.java =================================================================== --- trunk/core/org.cishell.framework/src/org/cishell/service/guibuilder/SelectionListener.java 2006-06-29 20:56:29 UTC (rev 79) +++ trunk/core/org.cishell.framework/src/org/cishell/service/guibuilder/SelectionListener.java 2006-06-30 19:05:13 UTC (rev 80) @@ -9,12 +9,29 @@ * Created on Jun 14, 2006 at Indiana University. * * Contributors: - * Indiana University - + * Indiana University - Initial API * ***************************************************************************/ package org.cishell.service.guibuilder; import java.util.Dictionary; +/** + * A listener that is notified when all values entered by a {@link GUI} user + * have been validated and they have clicked 'Ok' to proceed or if they + * cancelled the operation + * + * @author Bruce Herr (bh...@bh...) + */ public interface SelectionListener { - public boolean hitOk(Dictionary valuesEntered); + /** + * Notification that the user hit 'Ok' along with the data they entered + * + * @param valuesEntered The data the user entered + */ + public void hitOk(Dictionary valuesEntered); + + /** + * Notification that the user cancelled the operation + */ + public void cancelled(); } Added: trunk/core/org.cishell.framework/src/org/cishell/service/guibuilder/package.html =================================================================== --- trunk/core/org.cishell.framework/src/org/cishell/service/guibuilder/package.html (rev 0) +++ trunk/core/org.cishell.framework/src/org/cishell/service/guibuilder/package.html 2006-06-30 19:05:13 UTC (rev 80) @@ -0,0 +1,27 @@ +<!doctype html public "-//w3c//dtd html 4.0 transitional//en"> +<html> +<head> + <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> + <title>org.cishell.framework.datamodel Package-level Javadoc</title> +<!-- +/* **************************************************************************** + * CIShell: Cyberinfrastructure Shell, An Algorithm Integration Framework. + * + * All rights reserved. This program and the accompanying materials are made + * available under the terms of the Apache License v2.0 which accompanies + * this distribution, and is available at: + * http://www.apache.org/licenses/LICENSE-2.0.html + * + * Created on Jun 30, 2006 at Indiana University. + * + * Contributors: + * Indiana University - Initial API Documentation + * ***************************************************************************/ +--> +</head> +<body>Provides the specification for the CIShell GUI builder service +<h2>Package Specification</h2> +This package specifies the API related to the GUI builder service. + +</body> +</html> \ No newline at end of file This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
