[SAGA-RG] saga-ogf SVN commit 1270: /trunk/documents/saga-core-binding-java/implementation/VU/
ceriel at cs.vu.nl
ceriel at cs.vu.nl
Wed May 19 10:00:11 CDT 2010
User: svn_ceriel
Date: 2010/05/19 10:00 AM
Added:
/trunk/documents/saga-core-binding-java/implementation/VU/src/
overview.html
Removed:
/trunk/documents/saga-core-binding-java/implementation/VU/
overview.html
Modified:
/trunk/documents/saga-core-binding-java/implementation/VU/src/org/ogf/saga/bootstrap/
ImplementationBootstrapLoader.java
/trunk/documents/saga-core-binding-java/implementation/VU/src/org/ogf/saga/context/
ContextFactory.java
/trunk/documents/saga-core-binding-java/implementation/VU/src/org/ogf/saga/file/
FileFactory.java
/trunk/documents/saga-core-binding-java/implementation/VU/src/org/ogf/saga/namespace/
NSDirectory.java, NSEntry.java
Log:
Fixed a couple of javadoc bugs, moved overview.html to the right place.
File Changes:
Directory: /trunk/documents/saga-core-binding-java/implementation/VU/
=====================================================================
File [removed]: overview.html
Delta lines: +0 -139
===================================================================
--- trunk/documents/saga-core-binding-java/implementation/VU/overview.html 2010-05-19 14:19:09 UTC (rev 1269)
+++ trunk/documents/saga-core-binding-java/implementation/VU/overview.html 2010-05-19 14:59:05 UTC (rev 1270)
@@ -1,139 +0,0 @@
-<html>
-
- <head>
- <meta name=Title
- content="The SAGA Java Language Bindings"
- <title>The SAGA Java Language Bindings</title>
- </head>
-
- <body>
-
- <p>
- This overview discusses some of the general, Java-specific design
- considerations for the classes and interfaces from the
- language-independent SAGA specification (GFD.90).
- </p>
-
- <h2>Java language version</h2>
-
- <p>
- The Java language version used is the one provided in J2SE 5.0
- This version of the Java language is widely available and,
- in contrast to earlier versions, this version provides generics and
- enumerated types, features used in the SAGA language bindings
- for Java.
- Also, this version provides the {@link java.util.concurrent}
- package, which is not available in earlier versions, and which is
- used for the Java language bindings of SAGA tasks.
- </p>
-
- <h2>Identifiers</h2>
-
- <p>
- Various identifiers as used in the language-independent SAGA
- specification are changed slightly to obey Java conventions
- (for instance, <code>set_data</code> became <code>setData</code>,
- enumeration literals are completely capitalized)
- or to avoid conflicts with already existing method names
- (<code>wait</code> is replaced by <code>waitFor</code>).
- </p>
-
- <h2>Concurrency control and thread-safety</h2>
-
- <p>
- Java SAGA implementations must be thread-safe. Multiple application
- threads are allowed to access a common SAGA object. However, no
- particular order is enforced, unless the application itself does so.
- </p>
-
- <h2>File I/O and Java file streams</h2>
-
- <p>
- Earlier experience with JavaGAT
- has shown that having implementations of
- the Java streams {@link java.io.InputStream} and
- {@link java.io.OutputStream} is very much appreciated by
- Java application programmers, since these
- are the types on which most Java I/O is based. Therefore, it
- was decided to add specifications for
- {@link org.ogf.saga.file.FileInputStream FileInputStream} and
- {@link org.ogf.saga.file.FileOutputStream FileOutputStream}
- to the file package.
- The {@link org.ogf.saga.file.File File} class as specified in the
- SAGA specifications is also specified in the Java language bindings.
- Of course, implementations and factories
- may throw the
- {@link org.ogf.saga.error.NotImplementedException NotImplementedException}
- exception when methods or complete classes cannot be implemented.
- </p>
-
- <p>
- Also, methods were added to {@link org.ogf.saga.stream.Stream Stream}
- to obtain the usual java IO streams.
- </p>
-
- <h2>Error handling</h2>
-
- <p>
- The SAGA specifications refer to POSIX error return codes for several
- methods. However, it is not to be expected that these will be available
- in existing Java Grid middleware. Also, in Java, error conditions are
- supposed to be passed on by means of exceptions. Therefore, it was
- decided that where the SAGA specifications refer to POSIX error codes,
- a {@link org.ogf.saga.error.SagaIOException SagaIOException}
- is to be thrown in these cases. If an error code is available,
- it is stored in the exception object.
- </p>
-
- <h2>Features unavailable in Java: permissions, links</h2>
-
- <p>
- For some features of the SAGA specifications, most notably permissions
- and links, Java just does not provide building blocks, even locally.
- Java is not a systems programming language.
- Nevertheless, all methods concerning links and permissions are specified
- in the Java language bindings. SAGA application writers should not be
- surprised, however, if SAGA implementations throw a
- <code>NotImplemented</code> exception when these methods are invoked.
- </p>
-
- <h2>Prescribing the API for applications and SAGA implementors</h2>
-
- <p>
- The aim of having bindings of the SAGA API specification to certain programming
- languages is to define the precise syntax and semantics of the SAGA
- functionality, in the given language. This language binding can be seen as
- a contract between applications and SAGA implementors: both parties can
- safely assume that exactly the classes and interfaces described in this
- document will be either provided or requested for.
- </p>
-
- <p>
- For facilitating both application writing and implementing SAGA,
- providing the Java language binding in the form of directly usable files
- is considered important. It has been decided to provide both interfaces and
- classes from the language-independent SAGA specification in the form of
- Java interfaces.
- This leaves SAGA implementations with the task of writing
- classes that implement these interfaces. For allowing applications to create
- SAGA objects, the interfaces are accompanied by factory classes.
- Java implementations of SAGA must implement the interfaces and factories
- as specified here.
- </p>
-
- <p>
- This setup requires a bootstrap mechanism for creating factory objects.
- This is realized with the
- {@link org.ogf.saga.bootstrap.SagaFactory SagaFactory}
- interface, and the
- {@link org.ogf.saga.bootstrap.ImplementationBootstrapLoader ImplementationBootstrapLoader} class, as described here.
- This mechanism uses the <code>saga.factory</code> system property,
- to be set by the user to point to an implementation-specific
- metafactory, which in turn has methods to create factories for all
- SAGA packages.
- </p>
-
- </body>
-
-</html>
-
Directory: /trunk/documents/saga-core-binding-java/implementation/VU/src/org/ogf/saga/bootstrap/
================================================================================================
File [modified]: ImplementationBootstrapLoader.java
Delta lines: +0 -2
===================================================================
--- trunk/documents/saga-core-binding-java/implementation/VU/src/org/ogf/saga/bootstrap/ImplementationBootstrapLoader.java 2010-05-19 14:19:09 UTC (rev 1269)
+++ trunk/documents/saga-core-binding-java/implementation/VU/src/org/ogf/saga/bootstrap/ImplementationBootstrapLoader.java 2010-05-19 14:59:05 UTC (rev 1270)
@@ -74,8 +74,6 @@
* Creates a buffer factory.
*
* @return a buffer factory.
- * @throws NotImplementedException
- * is thrown when buffers are not implemented.
* @throws NoSuccessException
* is thrown when the Saga factory could not be created.
*/
Directory: /trunk/documents/saga-core-binding-java/implementation/VU/src/org/ogf/saga/context/
==============================================================================================
File [modified]: ContextFactory.java
Delta lines: +0 -4
===================================================================
--- trunk/documents/saga-core-binding-java/implementation/VU/src/org/ogf/saga/context/ContextFactory.java 2010-05-19 14:19:09 UTC (rev 1269)
+++ trunk/documents/saga-core-binding-java/implementation/VU/src/org/ogf/saga/context/ContextFactory.java 2010-05-19 14:59:05 UTC (rev 1270)
@@ -3,7 +3,6 @@
import org.ogf.saga.bootstrap.ImplementationBootstrapLoader;
import org.ogf.saga.error.IncorrectStateException;
import org.ogf.saga.error.NoSuccessException;
-import org.ogf.saga.error.NotImplementedException;
import org.ogf.saga.error.TimeoutException;
/**
@@ -56,9 +55,6 @@
* Constructs a security context.
*
* @return the security context.
- * @exception NotImplementedException
- * is thrown if the implementation does not provide an
- * implementation of this method.
* @exception IncorrectStateException
* @exception TimeoutException
* is thrown when a remote operation did not complete successfully
Directory: /trunk/documents/saga-core-binding-java/implementation/VU/src/org/ogf/saga/file/
===========================================================================================
File [modified]: FileFactory.java
Delta lines: +3 -11
===================================================================
--- trunk/documents/saga-core-binding-java/implementation/VU/src/org/ogf/saga/file/FileFactory.java 2010-05-19 14:19:09 UTC (rev 1269)
+++ trunk/documents/saga-core-binding-java/implementation/VU/src/org/ogf/saga/file/FileFactory.java 2010-05-19 14:59:05 UTC (rev 1270)
@@ -242,9 +242,9 @@
* data to be used.
* @return
* the IOVec.
- * @exception NotImplementedException
- * is thrown if the implementation does not provide an
- * implementation of this method.
+ * @exception NoSuccessException
+ * is thrown when the operation was not successfully performed,
+ * and none of the other exceptions apply.
* @exception BadParameterException
* is thrown when the implementation cannot handle
* the specified data buffer.
@@ -659,8 +659,6 @@
* @exception BadParameterException
* is thrown when the specified URL points to a directory,
* or is an invalid entry name.
- * @exception IncorrectStateException
- * is thrown when the NSDirectory is already closed.
* @exception IncorrectURLException
* is thrown if an implementation cannot handle the specified
* protocol, or that access to the specified entity via the
@@ -716,8 +714,6 @@
* @exception BadParameterException
* is thrown when the specified URL points to a directory,
* or is an invalid entry name.
- * @exception IncorrectStateException
- * is thrown when the NSDirectory is already closed.
* @exception IncorrectURLException
* is thrown if an implementation cannot handle the specified
* protocol, or that access to the specified entity via the
@@ -772,8 +768,6 @@
* @exception BadParameterException
* is thrown when the specified URL points to a directory,
* or is an invalid entry name.
- * @exception IncorrectStateException
- * is thrown when the NSDirectory is already closed.
* @exception IncorrectURLException
* is thrown if an implementation cannot handle the specified
* protocol, or that access to the specified entity via the
@@ -828,8 +822,6 @@
* @exception BadParameterException
* is thrown when the specified URL points to a directory,
* or is an invalid entry name.
- * @exception IncorrectStateException
- * is thrown when the NSDirectory is already closed.
* @exception IncorrectURLException
* is thrown if an implementation cannot handle the specified
* protocol, or that access to the specified entity via the
Directory: /trunk/documents/saga-core-binding-java/implementation/VU/src/org/ogf/saga/namespace/
================================================================================================
File [modified]: NSDirectory.java
Delta lines: +0 -2
===================================================================
--- trunk/documents/saga-core-binding-java/implementation/VU/src/org/ogf/saga/namespace/NSDirectory.java 2010-05-19 14:19:09 UTC (rev 1269)
+++ trunk/documents/saga-core-binding-java/implementation/VU/src/org/ogf/saga/namespace/NSDirectory.java 2010-05-19 14:59:05 UTC (rev 1270)
@@ -2279,7 +2279,6 @@
*
* @param mode
* the task mode.
- * @return the task.
* @param pattern
* name or pattern to find.
* @param flags
@@ -2299,7 +2298,6 @@
*
* @param mode
* the task mode.
- * @return the task.
* @param pattern
* name or pattern to find.
* @return the task.
File [modified]: NSEntry.java
Delta lines: +2 -2
===================================================================
--- trunk/documents/saga-core-binding-java/implementation/VU/src/org/ogf/saga/namespace/NSEntry.java 2010-05-19 14:19:09 UTC (rev 1269)
+++ trunk/documents/saga-core-binding-java/implementation/VU/src/org/ogf/saga/namespace/NSEntry.java 2010-05-19 14:59:05 UTC (rev 1270)
@@ -385,7 +385,7 @@
*/
public void link(URL target, int flags) throws NotImplementedException,
AuthenticationFailedException, AuthorizationFailedException,
- PermissionDeniedException, BadParameterException,
+ PermissionDeniedException, BadParameterException, DoesNotExistException,
IncorrectStateException, AlreadyExistsException, TimeoutException,
NoSuccessException, IncorrectURLException;
@@ -435,7 +435,7 @@
*/
public void link(URL target) throws NotImplementedException,
AuthenticationFailedException, AuthorizationFailedException,
- PermissionDeniedException, BadParameterException,
+ PermissionDeniedException, BadParameterException, DoesNotExistException,
IncorrectStateException, AlreadyExistsException, TimeoutException,
NoSuccessException, IncorrectURLException;
Directory: /trunk/documents/saga-core-binding-java/implementation/VU/src/
=========================================================================
File [added]: overview.html
Delta lines: +139 -0
===================================================================
--- trunk/documents/saga-core-binding-java/implementation/VU/src/overview.html 2010-05-19 14:19:09 UTC (rev 1269)
+++ trunk/documents/saga-core-binding-java/implementation/VU/src/overview.html 2010-05-19 14:59:05 UTC (rev 1270)
@@ -0,0 +1,139 @@
+<html>
+
+ <head>
+ <meta name=Title
+ content="The SAGA Java Language Bindings"
+ <title>The SAGA Java Language Bindings</title>
+ </head>
+
+ <body>
+
+ <p>
+ This overview discusses some of the general, Java-specific design
+ considerations for the classes and interfaces from the
+ language-independent SAGA specification (GFD.90).
+ </p>
+
+ <h2>Java language version</h2>
+
+ <p>
+ The Java language version used is the one provided in J2SE 5.0
+ This version of the Java language is widely available and,
+ in contrast to earlier versions, this version provides generics and
+ enumerated types, features used in the SAGA language bindings
+ for Java.
+ Also, this version provides the {@link java.util.concurrent}
+ package, which is not available in earlier versions, and which is
+ used for the Java language bindings of SAGA tasks.
+ </p>
+
+ <h2>Identifiers</h2>
+
+ <p>
+ Various identifiers as used in the language-independent SAGA
+ specification are changed slightly to obey Java conventions
+ (for instance, <code>set_data</code> became <code>setData</code>,
+ enumeration literals are completely capitalized)
+ or to avoid conflicts with already existing method names
+ (<code>wait</code> is replaced by <code>waitFor</code>).
+ </p>
+
+ <h2>Concurrency control and thread-safety</h2>
+
+ <p>
+ Java SAGA implementations must be thread-safe. Multiple application
+ threads are allowed to access a common SAGA object. However, no
+ particular order is enforced, unless the application itself does so.
+ </p>
+
+ <h2>File I/O and Java file streams</h2>
+
+ <p>
+ Earlier experience with JavaGAT
+ has shown that having implementations of
+ the Java streams {@link java.io.InputStream} and
+ {@link java.io.OutputStream} is very much appreciated by
+ Java application programmers, since these
+ are the types on which most Java I/O is based. Therefore, it
+ was decided to add specifications for
+ {@link org.ogf.saga.file.FileInputStream FileInputStream} and
+ {@link org.ogf.saga.file.FileOutputStream FileOutputStream}
+ to the file package.
+ The {@link org.ogf.saga.file.File File} class as specified in the
+ SAGA specifications is also specified in the Java language bindings.
+ Of course, implementations and factories
+ may throw the
+ {@link org.ogf.saga.error.NotImplementedException NotImplementedException}
+ exception when methods or complete classes cannot be implemented.
+ </p>
+
+ <p>
+ Also, methods were added to {@link org.ogf.saga.stream.Stream Stream}
+ to obtain the usual java IO streams.
+ </p>
+
+ <h2>Error handling</h2>
+
+ <p>
+ The SAGA specifications refer to POSIX error return codes for several
+ methods. However, it is not to be expected that these will be available
+ in existing Java Grid middleware. Also, in Java, error conditions are
+ supposed to be passed on by means of exceptions. Therefore, it was
+ decided that where the SAGA specifications refer to POSIX error codes,
+ a {@link org.ogf.saga.error.SagaIOException SagaIOException}
+ is to be thrown in these cases. If an error code is available,
+ it is stored in the exception object.
+ </p>
+
+ <h2>Features unavailable in Java: permissions, links</h2>
+
+ <p>
+ For some features of the SAGA specifications, most notably permissions
+ and links, Java just does not provide building blocks, even locally.
+ Java is not a systems programming language.
+ Nevertheless, all methods concerning links and permissions are specified
+ in the Java language bindings. SAGA application writers should not be
+ surprised, however, if SAGA implementations throw a
+ <code>NotImplemented</code> exception when these methods are invoked.
+ </p>
+
+ <h2>Prescribing the API for applications and SAGA implementors</h2>
+
+ <p>
+ The aim of having bindings of the SAGA API specification to certain programming
+ languages is to define the precise syntax and semantics of the SAGA
+ functionality, in the given language. This language binding can be seen as
+ a contract between applications and SAGA implementors: both parties can
+ safely assume that exactly the classes and interfaces described in this
+ document will be either provided or requested for.
+ </p>
+
+ <p>
+ For facilitating both application writing and implementing SAGA,
+ providing the Java language binding in the form of directly usable files
+ is considered important. It has been decided to provide both interfaces and
+ classes from the language-independent SAGA specification in the form of
+ Java interfaces.
+ This leaves SAGA implementations with the task of writing
+ classes that implement these interfaces. For allowing applications to create
+ SAGA objects, the interfaces are accompanied by factory classes.
+ Java implementations of SAGA must implement the interfaces and factories
+ as specified here.
+ </p>
+
+ <p>
+ This setup requires a bootstrap mechanism for creating factory objects.
+ This is realized with the
+ {@link org.ogf.saga.bootstrap.SagaFactory SagaFactory}
+ interface, and the
+ {@link org.ogf.saga.bootstrap.ImplementationBootstrapLoader ImplementationBootstrapLoader} class, as described here.
+ This mechanism uses the <code>saga.factory</code> system property,
+ to be set by the user to point to an implementation-specific
+ metafactory, which in turn has methods to create factories for all
+ SAGA packages.
+ </p>
+
+ </body>
+
+</html>
+
More information about the saga-rg
mailing list