Menu
▾
▴
[Unicore-cvs-commits] SF.net SVN: unicore: [1852] hila/trunk/hila-api/src/main/java/de/fzj/hila
|
From: <bj...@us...> - 2007-10-31 15:33:26
|
Revision: 1852
http://unicore.svn.sourceforge.net/unicore/?rev=1852&view=rev
Author: bjoernh
Date: 2007-10-31 08:33:22 -0700 (Wed, 31 Oct 2007)
Log Message:
-----------
documentation
Modified Paths:
--------------
hila/trunk/hila-api/src/main/java/de/fzj/hila/Attributes.java
hila/trunk/hila-api/src/main/java/de/fzj/hila/BaseHiLAFactory.java
hila/trunk/hila-api/src/main/java/de/fzj/hila/Config.java
hila/trunk/hila-api/src/main/java/de/fzj/hila/File.java
hila/trunk/hila-api/src/main/java/de/fzj/hila/Grid.java
hila/trunk/hila-api/src/main/java/de/fzj/hila/Site.java
hila/trunk/hila-api/src/main/java/de/fzj/hila/Storage.java
hila/trunk/hila-api/src/main/java/de/fzj/hila/Task.java
hila/trunk/hila-api/src/main/java/de/fzj/hila/TaskStatus.java
Modified: hila/trunk/hila-api/src/main/java/de/fzj/hila/Attributes.java
===================================================================
--- hila/trunk/hila-api/src/main/java/de/fzj/hila/Attributes.java 2007-10-31 15:31:24 UTC (rev 1851)
+++ hila/trunk/hila-api/src/main/java/de/fzj/hila/Attributes.java 2007-10-31 15:33:22 UTC (rev 1852)
@@ -1,5 +1,5 @@
/**
- * Copyright (c) 2005, Forschungszentrum Juelich
+ * Copyright (c) ${year}, Forschungszentrum Juelich
*
* All rights reserved.
*
@@ -27,7 +27,6 @@
* THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*/
-
package de.fzj.hila;
import java.util.Collection;
@@ -66,9 +65,9 @@
* @throws HiLAException
*/
public Set keySet() throws HiLAException;
-
+
public Site getSite();
-
+
public String toXMLString() throws HiLAException;
-
+
}
Modified: hila/trunk/hila-api/src/main/java/de/fzj/hila/BaseHiLAFactory.java
===================================================================
--- hila/trunk/hila-api/src/main/java/de/fzj/hila/BaseHiLAFactory.java 2007-10-31 15:31:24 UTC (rev 1851)
+++ hila/trunk/hila-api/src/main/java/de/fzj/hila/BaseHiLAFactory.java 2007-10-31 15:33:22 UTC (rev 1852)
@@ -40,9 +40,9 @@
{
this.scheme = scheme;
String sysprop = System.getProperty("hila." + this.scheme + ".xml");
- if (sysprop!=null)
+ if (sysprop != null)
{
- log.info("found :: hila." + this.scheme + ".xml = " + sysprop );
+ log.info("found :: hila." + this.scheme + ".xml = " + sysprop);
}
ArrayList<Resource> finder = new ArrayList<Resource>();
if (sysprop != null) finder.add(new FileSystemResource(new File(sysprop)));
@@ -63,7 +63,7 @@
{
cacheGrid();
}
- if (this.grid==null) throw new HiLAFactoryException("cannot get a Grid for "+this.scheme);
+ if (this.grid == null) throw new HiLAFactoryException("cannot get a Grid for " + this.scheme);
return this.grid;
}
Modified: hila/trunk/hila-api/src/main/java/de/fzj/hila/Config.java
===================================================================
--- hila/trunk/hila-api/src/main/java/de/fzj/hila/Config.java 2007-10-31 15:31:24 UTC (rev 1851)
+++ hila/trunk/hila-api/src/main/java/de/fzj/hila/Config.java 2007-10-31 15:33:22 UTC (rev 1852)
@@ -4,18 +4,14 @@
* All rights reserved.
*
* Redistribution and use in source and binary forms, with or without modification, are
- * permitted provided that the following conditions are met:
+ * permitted provided that the following conditions are met: * Redistributions of source
+ * code must retain the above copyright notice, this list of conditions and the following
+ * disclaimer. * Redistributions in binary form must reproduce the above copyright notice,
+ * this list of conditions and the following disclaimer in the documentation and/or other
+ * materials provided with the distribution. * Neither the name of the Forschungszentrum
+ * Juelich nor the names of its contributors may be used to endorse or promote products
+ * derived from this software without specific prior written permission.
*
- * * Redistributions of source code must retain the above copyright
- * notice, this list of conditions and the following disclaimer.
- * * Redistributions in binary form must reproduce the above copyright
- * notice, this list of conditions and the following disclaimer in
- * the documentation and/or other materials provided with the
- * distribution.
- * * Neither the name of the Forschungszentrum Juelich nor the names of its
- * contributors may be used to endorse or promote products derived
- * from this software without specific prior written permission.
- *
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY
* EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
* MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL
@@ -27,7 +23,6 @@
* THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*/
-
package de.fzj.hila;
import java.util.Map;
@@ -40,18 +35,18 @@
*/
public interface Config
{
-
+
public Set<Location> getAllSiteLocations();
-
+
/**
*
* @param location
* @return
*/
public ID findIDforLocation(Location location);
-
+
public Map getExtraInformationForLocation(Location location);
-
+
public boolean exists(Location location);
-
+
}
Modified: hila/trunk/hila-api/src/main/java/de/fzj/hila/File.java
===================================================================
--- hila/trunk/hila-api/src/main/java/de/fzj/hila/File.java 2007-10-31 15:31:24 UTC (rev 1851)
+++ hila/trunk/hila-api/src/main/java/de/fzj/hila/File.java 2007-10-31 15:33:22 UTC (rev 1852)
@@ -4,18 +4,15 @@
* All rights reserved.
*
* Redistribution and use in source and binary forms, with or without modification, are
- * permitted provided that the following conditions are met:
+ * permitted provided that the following conditions are met:
+ * * Redistributions of source code must retain the above copyright notice, this list of
+ * conditions and the following disclaimer. * Redistributions in binary form must
+ * reproduce the above copyright notice, this list of conditions and the following
+ * disclaimer in the documentation and/or other materials provided with the distribution. *
+ * Neither the name of the Forschungszentrum Juelich nor the names of its contributors may
+ * be used to endorse or promote products derived from this software without specific
+ * prior written permission.
*
- * * Redistributions of source code must retain the above copyright
- * notice, this list of conditions and the following disclaimer.
- * * Redistributions in binary form must reproduce the above copyright
- * notice, this list of conditions and the following disclaimer in
- * the documentation and/or other materials provided with the
- * distribution.
- * * Neither the name of the Forschungszentrum Juelich nor the names of its
- * contributors may be used to endorse or promote products derived
- * from this software without specific prior written permission.
- *
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY
* EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
* MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL
@@ -27,7 +24,6 @@
* THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*/
-
package de.fzj.hila;
import java.util.Date;
@@ -36,7 +32,8 @@
import de.fzj.hila.exceptions.HiLAException;
/**
- * models a file in the Grid
+ * Models a file in the Grid. Files are always contained inside a Storage.
+ * A HiLA File is conceptually similar to a {@link java.io.File}.
*
* @author roger
*/
@@ -50,42 +47,88 @@
*/
public List<File> ls() throws HiLAException;
+ /**
+ * A File is always contained in a Storage.
+ * @return The Storage that this File is contained in.
+ */
public Storage getStorage();
+ /**
+ *
+ * @return true, if this File is a directory, false otherwise.
+ * @throws HiLAException
+ */
public boolean isDirectory() throws HiLAException;
+ /**
+ *
+ * @return Whether this File is the root, i.e. base directory, of it's Storage
+ * @throws HiLAException
+ */
public boolean isRoot() throws HiLAException;
-
+
public Date lastModified() throws HiLAException;
+ /**
+ *
+ * @return The size of this File in bytes.
+ */
public long size();
+ /**
+ *
+ * @return True, if this File has the execution permission set.
+ */
public boolean canExecute();
+ /**
+ *
+ * @return True, if this File has the read permission set.
+ */
public boolean canRead();
+ /**
+ *
+ * @return True, if this File has the write permission set.
+ */
public boolean canWrite();
public File getParentFile() throws HiLAException;
-
+
public File getChildFile(String chilad) throws HiLAException;
public String getName();
public boolean mkdir() throws HiLAException;
-
+
public boolean chmod(boolean read, boolean write, boolean execute) throws HiLAException;
+ /**
+ * Check whether this file exists
+ * @return True if the File exists, False otherwise.
+ * @throws HiLAException
+ */
public boolean exists() throws HiLAException;
+ /**
+ * Delete the File
+ * @return True if deletion was successful, False otherwise.
+ * @throws HiLAException
+ */
public boolean delete() throws HiLAException;
+ /**
+ * Create a copy of this File inside the same {@link Storage}
+ * @param to
+ * @param overwrite
+ * @throws HiLAException
+ */
public void copyTo(File to, boolean overwrite) throws HiLAException;
public void moveTo(File to, boolean overwrite) throws HiLAException;
public String getPath();
-
+
public void refresh() throws HiLAException;
/**
@@ -93,7 +136,7 @@
*
* @param remoteto
* @return
- * @throws HiLAException
+ * @throws HiLAException
*/
public Task transfer(File remoteto, boolean overwrite) throws HiLAException;
Modified: hila/trunk/hila-api/src/main/java/de/fzj/hila/Grid.java
===================================================================
--- hila/trunk/hila-api/src/main/java/de/fzj/hila/Grid.java 2007-10-31 15:31:24 UTC (rev 1851)
+++ hila/trunk/hila-api/src/main/java/de/fzj/hila/Grid.java 2007-10-31 15:33:22 UTC (rev 1852)
@@ -35,26 +35,77 @@
import de.fzj.hila.exceptions.HiLAException;
/**
- * top level class modelling the whole 'Grid'
+ * top level class modelling the whole 'Grid'.
+ *
+ * A Grid is the entry point to a middleware specific Grid.
* @author roger
*/
public interface Grid extends Submitable, Locatable
{
+ /**
+ * The {@link Config} is responsible for the configuration part of HiLA. This is where
+ * the security is set up. Some implementations support a site-by-site basis of
+ * security settings, others use more general configuration.
+ * @return
+ */
public Config getConfig();
+ /**
+ * Set {@link Config} for this Grid.
+ * @param config
+ */
public void setConfig(Config config);
+ /**
+ * Get the list of {@link Site}s for this Grid. This is for implementations that
+ * use locally configured {@link Site}s rather than a central registry. A combination
+ * of using a registry and statically configuring {@link Site}s is possible.
+ * @return A list of configured {@link Site}s
+ * @throws HiLAException
+ */
public List<Site> getAllSites() throws HiLAException;
+ /**
+ * Locate a Site by its {@link Location}.
+ * @param location The {@link Location}
+ * @return The {@link Site}. <code>null</code> if no {@link Site} exists for the {@link Location}
+ * @throws HiLAException
+ * @see locateStorage(Location), locateFile(Location), locate(Location)
+ */
public Site locateSite(Location location) throws HiLAException;
+ /**
+ * Locate a {@link Storage} by its {@link Location}
+ * @see locateSite(Location), locateFile(Location), locate(Location)
+ * @param location The {@link Location}
+ * @return The {@link Storage}. <code>null</code> if no {@link Storage} exists for the {@link Location}.
+ * @throws HiLAException
+ */
public Storage locateStorage(Location location) throws HiLAException;
+ /**
+ * Locate a {@link File} by its {@link Location}. A {@link File} is something virtual and
+ * will be returned by this method, even if the file doesn't exist in the Storage. Cf. {@link java.io.File}.
+ * @see locateSite(Location), locateStorage(Location), locate(Location)
+ * @param location The {@link Location}
+ * @return The {@link File}.
+ * @throws HiLAException
+ */
public File locateFile(Location location) throws HiLAException;
+ /**
+ * General method to locate artifacts on the {@link Grid}. It returns a generic
+ * {@link Locatable}, which can be used for browsing any {@link Locatable} artifacts.
+ * @param location The {@link Location}
+ * @return The {@link Locatable}
+ * @throws HiLAException
+ */
public Locatable locate(Location location) throws HiLAException;
+ /**
+ * TODO write reasonable documentation
+ */
public void close();
}
Modified: hila/trunk/hila-api/src/main/java/de/fzj/hila/Site.java
===================================================================
--- hila/trunk/hila-api/src/main/java/de/fzj/hila/Site.java 2007-10-31 15:31:24 UTC (rev 1851)
+++ hila/trunk/hila-api/src/main/java/de/fzj/hila/Site.java 2007-10-31 15:33:22 UTC (rev 1852)
@@ -36,32 +36,62 @@
import de.fzj.hila.exceptions.HiLAException;
/**
- * a Grid consists of a collection of Site objects, and and each Site
- * contains a collection of Storages and a collection of Tasks as immediate Locatable chiladren
+ * <p>A Grid consists of a collection of Site objects, and each Site
+ * contains a collection of {@link Storage}s and a collection of {@link Task}s as immediate {@link Locatable} children.</p>
*
- * it is also Submitable, and contains a collection of running Tasks
+ * It is also {@link Submitable}, and contains a collection of running Tasks.
*
* @author roger
*/
public interface Site extends Submitable, Locatable
{
/**
- * kind of like a ping, only works if the client has valid credentials
+ * Kind of like a ping, only works if the client has valid credentials.
*
- * @return
+ * @return True, if the Site is reachable, false otherwise.
*/
public boolean ok();
+ /**
+ * Get a list of available {@link StorageType}s
+ * @return
+ * @throws HiLAException
+ */
public List<StorageType> getStoragesTypes() throws HiLAException;
+ /**
+ * Get a Storage based on its {@link StorageType}
+ * @param type
+ * @return
+ * @throws HiLAException
+ */
public Storage getStorage(StorageType type) throws HiLAException;
+ /**
+ * Get a List of available {@link Storage}s
+ * @return
+ * @throws HiLAException
+ */
public List<Storage> getStorages() throws HiLAException;
+ /**
+ * @see Attributes
+ * @return
+ * @throws HiLAException
+ */
public Attributes getAttributes() throws HiLAException;
+ /**
+ *
+ * @return The Grid that this Site belongs to.
+ */
public Grid getGrid();
+ /**
+ * Get the date when this Site has been started.
+ * @return The Date when this Site has been started.
+ * @throws HiLAException
+ */
public Date upSince() throws HiLAException;
}
Modified: hila/trunk/hila-api/src/main/java/de/fzj/hila/Storage.java
===================================================================
--- hila/trunk/hila-api/src/main/java/de/fzj/hila/Storage.java 2007-10-31 15:31:24 UTC (rev 1851)
+++ hila/trunk/hila-api/src/main/java/de/fzj/hila/Storage.java 2007-10-31 15:33:22 UTC (rev 1852)
@@ -33,17 +33,31 @@
import de.fzj.hila.exceptions.HiLAException;
/**
- * a Site can have a number of Storage(s) associated with it
+ * A Site can have a number of Storage(s) associated with it.
*
* @author roger
*/
public interface Storage extends Locatable
{
+ /**
+ * Get the Site that this storage belongs to.
+ * @return The Site. Could be <code>null</code> if this Storage doesn't belong to any Site.
+ */
public Site getSite();
+ /**
+ *
+ * @return The {@link StorageType}
+ */
public StorageType getType();
+ /**
+ *
+ * @param path The path inside this Storage that's turned into a File.
+ * @return The {@link File} at this path.
+ * @throws HiLAException
+ */
public File asFile(String path) throws HiLAException;
}
Modified: hila/trunk/hila-api/src/main/java/de/fzj/hila/Task.java
===================================================================
--- hila/trunk/hila-api/src/main/java/de/fzj/hila/Task.java 2007-10-31 15:31:24 UTC (rev 1851)
+++ hila/trunk/hila-api/src/main/java/de/fzj/hila/Task.java 2007-10-31 15:33:22 UTC (rev 1852)
@@ -44,20 +44,54 @@
public interface Task extends Locatable
{
+ /**
+ * Start the Task in a synchronous manner, i.e. start and block on it until it's
+ * finished. Before starting, all given {@link File}s are transferred to the
+ * Task's working directory.
+ * @param files
+ * @throws HiLAException
+ */
public void startSync(File... files) throws HiLAException;
+ /**
+ * Start the Task in an asynchronous manner. Unlike startSync(), this method doesn't
+ * block on the task, but returns (almost) immediately.
+ * @param files
+ * @throws HiLAException
+ */
public void startASync(File... files) throws HiLAException;
public void setAutomaticallyAdvanceToCleanup(boolean aatc);
+ /**
+ * Block on a running Task until it gets to a final state.
+ * @return Status of the Task
+ */
public TaskStatus block();
+ /**
+ * Block on a running Task until it gets to a final state or a time out is reached.
+ * @param timeout Don't block forever
+ * @return Status of the Task
+ */
public TaskStatus block(long timeout);
+ /**
+ * Abort a running Task
+ * @throws HiLAException
+ */
public void abort() throws HiLAException;
+ /**
+ * Cancel a running Task.
+ * @throws HiLAException
+ */
public void cancel() throws HiLAException;
+ /**
+ * Cleanup the Task, i.e. delete working directory and generally free it's resources.
+ * @throws HiLAException
+ */
public void cleanup() throws HiLAException;
/**
@@ -68,30 +102,92 @@
*/
public TaskStatus status() throws HiLAException;
+ /**
+ * Get this tasks identifier.
+ * @return The <code>Task</code>'s identifier.
+ * @throws HiLAException
+ */
public String getID() throws HiLAException;
public String getTaskName() throws HiLAException;
+ /**
+ * Get the Site this Task is running on.
+ * @return The Site that this task is executed on.
+ */
public Site getSite();
+ /**
+ * <p>Get File's from working directory of a Task. This is a potentially long running
+ * operation, as it transfers files first and then returns a list of {@link File}s.</p>
+ *
+ * <p>If you're interested in individual {@link de.fzj.hila.File}s from the working directory,
+ * you can try and ls() a Task.</p>
+ *
+ * TODO offer an official method to query for the working directory.
+ * @return
+ */
public List<File> getOutcomeFiles();
+ /**
+ * Copy standard output of the Task into a local {@link File}.
+ * @return The local file containing STDOUT of the Task
+ */
public File getStdOut();
+ /**
+ * Copy standard error of the Task into a local {@link File}.
+ * @return The local file containing STDERR of the Task
+ */
public File getStdErr();
+ /**
+ * The log returned here does not have any special form. It's simply a String that may
+ * or may not be returned by a target middleware.
+ * @return Log of this Task.
+ * @throws HiLAException
+ */
public String getLog() throws HiLAException;
+ /**
+ * Register a {@link StatusChangedListener} to be notified on changes of status of this Task.
+ * @param listener
+ */
public void registerStatusChangedListener(StatusChangedListener listener);
+ /**
+ * Remove a {@link StatusChangedListener} from this Task. If the listener didn't exist
+ * as a listener of this Task, do nothing.
+ * @param listener
+ */
public void removeStatusChangedListener(StatusChangedListener listener);
+ /**
+ *
+ * @return An associative map of TaskStatus and History.
+ * @throws HiLAException
+ */
public Map<TaskStatus, History> getHistory() throws HiLAException;
+ /**
+ * History is a more structured form of the Log. It associates a Date and a reason.
+ * It's usually stored inside a Map<TaskStatus, History>.
+ * @see getHistory()
+ * @author bjoernh
+ *
+ */
public static interface History
{
+ /**
+ *
+ * @return The Date of this History item.
+ */
public Date getDate();
+ /**
+ *
+ * @return A descriptive String of what happened.
+ */
public String getReason();
}
Modified: hila/trunk/hila-api/src/main/java/de/fzj/hila/TaskStatus.java
===================================================================
--- hila/trunk/hila-api/src/main/java/de/fzj/hila/TaskStatus.java 2007-10-31 15:31:24 UTC (rev 1851)
+++ hila/trunk/hila-api/src/main/java/de/fzj/hila/TaskStatus.java 2007-10-31 15:33:22 UTC (rev 1852)
@@ -56,6 +56,7 @@
*
* *=final state
*
+ * TODO Remove states not defined in OGSA-BES, this has many implications for existing implementations
* @author roger, bjoernh
*/
public enum TaskStatus
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|