/hg/icedtea-web: Minor javadoc enhancements
jvanek at icedtea.classpath.org
jvanek at icedtea.classpath.org
Fri May 23 11:38:32 UTC 2014
changeset 7703f77be921 in /hg/icedtea-web
details: http://icedtea.classpath.org/hg/icedtea-web?cmd=changeset;node=7703f77be921
author: Jiri Vanek <jvanek at redhat.com>
date: Fri May 23 13:38:14 2014 +0200
Minor javadoc enhancements
diffstat:
ChangeLog | 12 +
netx/net/sourceforge/jnlp/cache/CacheEntry.java | 5 +-
netx/net/sourceforge/jnlp/cache/CacheUtil.java | 9 +
netx/net/sourceforge/jnlp/cache/Resource.java | 7 +
netx/net/sourceforge/jnlp/cache/ResourceTracker.java | 14 ++
netx/net/sourceforge/jnlp/runtime/ApplicationInstance.java | 19 ++-
netx/net/sourceforge/jnlp/util/FileUtils.java | 16 +-
tests/test-extensions/net/sourceforge/jnlp/ServerAccess.java | 76 +++++++++--
8 files changed, 133 insertions(+), 25 deletions(-)
diffs (truncated from 541 to 500 lines):
diff -r 4e236cc7181c -r 7703f77be921 ChangeLog
--- a/ChangeLog Thu May 22 15:45:37 2014 -0400
+++ b/ChangeLog Fri May 23 13:38:14 2014 +0200
@@ -1,3 +1,15 @@
+2014-05-21 Jiri Vanek <jvanek at redhat.com>
+
+ Minor javadoc enhancements
+ * netx/net/sourceforge/jnlp/cache/CacheEntry.java: added or filled some javadocs
+ * netx/net/sourceforge/jnlp/cache/CacheUtil.java: same
+ * netx/net/sourceforge/jnlp/cache/Resource.java: same
+ * netx/net/sourceforge/jnlp/cache/ResourceTracker.java: same
+ * netx/net/sourceforge/jnlp/runtime/ApplicationInstance.java: same
+ * netx/net/sourceforge/jnlp/util/FileUtils.java: same
+ * tests/test-extensions/net/sourceforge/jnlp/ServerAccess.java: same
+
+
2014-05-22 Jie Kang <jkang at redhat.com>
* netx/net/sourceforge/jnlp/security/policyeditor/PolicyEditor.java
diff -r 4e236cc7181c -r 7703f77be921 netx/net/sourceforge/jnlp/cache/CacheEntry.java
--- a/netx/net/sourceforge/jnlp/cache/CacheEntry.java Thu May 22 15:45:37 2014 -0400
+++ b/netx/net/sourceforge/jnlp/cache/CacheEntry.java Fri May 23 13:38:14 2014 +0200
@@ -75,6 +75,7 @@
/**
* Returns the remote location this entry caches.
+ * @return URL same as the one on which this entry was created
*/
public URL getLocation() {
return location;
@@ -83,7 +84,7 @@
/**
* Returns the time in the local system clock that the file was
* most recently checked for an update.
- * @return
+ * @return when the item was updated (in ms)
*/
public long getLastUpdated() {
return getLongKey(KEY_LAST_UPDATED);
@@ -92,7 +93,7 @@
/**
* Sets the time in the local system clock that the file was
* most recently checked for an update.
- * @param updatedTime
+ * @param updatedTime the time (in ms) to be set as last updated time
*/
public void setLastUpdated(long updatedTime) {
setLongKey(KEY_LAST_UPDATED, updatedTime);
diff -r 4e236cc7181c -r 7703f77be921 netx/net/sourceforge/jnlp/cache/CacheUtil.java
--- a/netx/net/sourceforge/jnlp/cache/CacheUtil.java Thu May 22 15:45:37 2014 -0400
+++ b/netx/net/sourceforge/jnlp/cache/CacheUtil.java Fri May 23 13:38:14 2014 +0200
@@ -182,6 +182,7 @@
* Note: Because of how our caching system works, deleting jars of another javaws
* process is using them can be quite disasterous. Hence why Launcher creates lock files
* and we check for those by calling {@link #okToClearCache()}
+ * @return true if the cache could be cleared and was cleared
*/
public static boolean clearCache() {
@@ -297,6 +298,9 @@
* Returns whether the resource can be cached as a local file;
* if not, then URLConnection.openStream can be used to obtain
* the contents.
+ * @param source the url of resource
+ * @param version version of resource
+ * @return whether this resource can be cached
*/
public static boolean isCacheable(URL source, Version version) {
if (source == null)
@@ -444,6 +448,7 @@
*
* @param source the remote location
* @param version the file version to write to
+ * @return the stream towrite to resource
*/
public static OutputStream getOutputStream(URL source, Version version) throws IOException {
File localFile = getCacheFile(source, version);
@@ -456,6 +461,9 @@
* Copies from an input stream to an output stream. On
* completion, both streams will be closed. Streams are
* buffered automatically.
+ * @param is stream to read from
+ * @param os stream to write to
+ * @throws java.io.IOException if copy fails
*/
public static void streamCopy(InputStream is, OutputStream os) throws IOException {
if (!(is instanceof BufferedInputStream))
@@ -511,6 +519,7 @@
* Waits until the resources are downloaded, while showing a
* progress indicator.
*
+ * @param app application instance with context for this resource
* @param tracker the resource tracker
* @param resources the resources to wait for
* @param title name of the download
diff -r 4e236cc7181c -r 7703f77be921 netx/net/sourceforge/jnlp/cache/Resource.java
--- a/netx/net/sourceforge/jnlp/cache/Resource.java Thu May 22 15:45:37 2014 -0400
+++ b/netx/net/sourceforge/jnlp/cache/Resource.java Fri May 23 13:38:14 2014 +0200
@@ -109,8 +109,13 @@
/**
* Return a shared Resource object representing the given
* location and version.
+ * @param location final location of resource
+ * @param requestVersion final version of resource
+ * @param updatePolicy final policy for updating
+ * @return new resource, which is already added in resources list
*/
public static Resource getResource(URL location, Version requestVersion, UpdatePolicy updatePolicy) {
+ //TODO -rename to create resource?
synchronized (resources) {
Resource resource = new Resource(location, requestVersion, updatePolicy);
@@ -133,6 +138,7 @@
/**
* Returns the remote location of the resource.
+ * @return the same location as the one with which this resource was created
*/
public URL getLocation() {
return location;
@@ -378,6 +384,7 @@
/**
* Adds the tracker to the list of trackers monitoring this
* resource.
+ * @param tracker to observing resource
*/
public void addTracker(ResourceTracker tracker) {
synchronized (trackers) {
diff -r 4e236cc7181c -r 7703f77be921 netx/net/sourceforge/jnlp/cache/ResourceTracker.java
--- a/netx/net/sourceforge/jnlp/cache/ResourceTracker.java Thu May 22 15:45:37 2014 -0400
+++ b/netx/net/sourceforge/jnlp/cache/ResourceTracker.java Fri May 23 13:38:14 2014 +0200
@@ -216,6 +216,7 @@
* not required as resources are reclaimed when the tracker is
* collected.
*
+ * @param location location of resource to be removed
* @throws IllegalResourceDescriptorException if the resource is not being tracked
*/
public void removeResource(URL location) {
@@ -308,6 +309,7 @@
* on each tracker that is monitoring the resource. Do not call
* this method with any locks because the listeners may call
* back to this ResourceTracker.
+ * @param resource resource on which event is fired
*/
protected void fireDownloadEvent(Resource resource) {
DownloadListener l[] = null;
@@ -407,6 +409,8 @@
* the cache.
* </p>
*
+ * @param location location of resource which stream will be obtained
+ * @return the stream of the resource
* @throws IOException if there was an error opening the stream
* @throws IllegalResourceDescriptorException if the resource is not being tracked
*/
@@ -432,6 +436,7 @@
* @param urls the resources to wait for
* @param timeout the time in ms to wait before returning, 0 for no timeout
* @return whether the resources downloaded before the timeout
+ * @throws java.lang.InterruptedException if thread is interrupted
* @throws IllegalResourceDescriptorException if the resource is not being tracked
*/
public boolean waitForResources(URL urls[], long timeout) throws InterruptedException {
@@ -481,6 +486,8 @@
* Returns whether a resource is available for use (ie, can be
* accessed with the getCacheFile method).
*
+ * @param location the resource location
+ * @return resource availability
* @throws IllegalResourceDescriptorException if the resource is not being tracked
*/
public boolean checkResource(URL location) {
@@ -495,6 +502,7 @@
* by the tracker because the tracker will only prefetch one
* resource at a time to conserve system resources.
*
+ * @param location the resource location
* @return true if the resource is already downloaded (or an error occurred)
* @throws IllegalResourceDescriptorException if the resource is not being tracked
*/
@@ -784,6 +792,8 @@
/**
* Open a URL connection and get the content length and other
* fields.
+ *
+ * @param resource the resource to initialize
*/
private void initializeResource(Resource resource) {
resource.fireDownloadEvent(); // fire CONNECTING
@@ -887,6 +897,10 @@
|| result == 308);
}
+ /**
+ *
+ * @return whether the return code is OK one - anything except <200,300)
+ */
public boolean isInvalid() {
return (result < 200 || result >= 300);
}
diff -r 4e236cc7181c -r 7703f77be921 netx/net/sourceforge/jnlp/runtime/ApplicationInstance.java
--- a/netx/net/sourceforge/jnlp/runtime/ApplicationInstance.java Thu May 22 15:45:37 2014 -0400
+++ b/netx/net/sourceforge/jnlp/runtime/ApplicationInstance.java Fri May 23 13:38:14 2014 +0200
@@ -92,6 +92,9 @@
/**
* Create an application instance for the file. This should be done in the
* appropriate {@link ThreadGroup} only.
+ * @param file jnlpfile for which the instance do exists
+ * @param group thread group to which it belongs
+ * @param loader loader for this application
*/
public ApplicationInstance(JNLPFile file, ThreadGroup group, ClassLoader loader) {
this.file = file;
@@ -103,6 +106,7 @@
/**
* Add an Application listener
+ * @param listener listener to be added
*/
public void addApplicationListener(ApplicationListener listener) {
listeners.add(ApplicationListener.class, listener);
@@ -110,6 +114,7 @@
/**
* Remove an Application Listener
+ * @param listener to be removed
*/
public void removeApplicationListener(ApplicationListener listener) {
listeners.remove(ApplicationListener.class, listener);
@@ -253,7 +258,8 @@
}
/**
- * Returns the JNLP file for this task.
+ * Returns the jnlpfile on which is this application based
+ * @return JNLP file for this task.
*/
public JNLPFile getJNLPFile() {
return file;
@@ -261,6 +267,7 @@
/**
* Returns the application title.
+ * @return the title of this application
*/
public String getTitle() {
return file.getTitle();
@@ -268,6 +275,7 @@
/**
* Returns whether the application is running.
+ * @return state of application
*/
public boolean isRunning() {
return !stopped;
@@ -317,6 +325,7 @@
/**
* Returns the thread group.
*
+ * @return thread group of this application, unless it is stopped
* @throws IllegalStateException if the app is not running
*/
public ThreadGroup getThreadGroup() throws IllegalStateException {
@@ -329,6 +338,7 @@
/**
* Returns the classloader.
*
+ * @return the classloader of this application, unless it is stopped
* @throws IllegalStateException if the app is not running
*/
public ClassLoader getClassLoader() throws IllegalStateException {
@@ -341,6 +351,7 @@
/**
* Adds a window that this application opened. When the
* application is disposed, these windows will also be disposed.
+ * @param window to be added
*/
protected void addWindow(Window window) {
weakWindows.add(window);
@@ -348,12 +359,16 @@
}
/**
- * Returns whether or not this jar is signed.
+ * Returns whether or not this application is signed.
*/
public boolean isSigned() {
return isSigned;
}
+ /**
+ *
+ * @return application context of this instance
+ */
public AppContext getAppContext() {
return appContext;
}
diff -r 4e236cc7181c -r 7703f77be921 netx/net/sourceforge/jnlp/util/FileUtils.java
--- a/netx/net/sourceforge/jnlp/util/FileUtils.java Thu May 22 15:45:37 2014 -0400
+++ b/netx/net/sourceforge/jnlp/util/FileUtils.java Fri May 23 13:38:14 2014 +0200
@@ -527,17 +527,25 @@
return lock;
}
- /**
- * helping dummy method to save String as file
+/**
+ * Method to save String as file in UTF-8 encoding.
*
- * @param content
- * @param f
+ * @param content which will be saved as it is saved in this String
+ * @param f file to be saved. No warnings provided
* @throws IOException
*/
public static void saveFile(String content, File f) throws IOException {
saveFile(content, f, "utf-8");
}
+ /**
+ * Method to save String as file in specified encoding/.
+ *
+ * @param content which will be saved as it is saved in this String
+ * @param f file to be saved. No warnings provided
+ * @param encoding of output byte representation
+ * @throws IOException
+ */
public static void saveFile(String content, File f, String encoding) throws IOException {
Writer output = new BufferedWriter(new OutputStreamWriter(new FileOutputStream(f), encoding));
output.write(content);
diff -r 4e236cc7181c -r 7703f77be921 tests/test-extensions/net/sourceforge/jnlp/ServerAccess.java
--- a/tests/test-extensions/net/sourceforge/jnlp/ServerAccess.java Thu May 22 15:45:37 2014 -0400
+++ b/tests/test-extensions/net/sourceforge/jnlp/ServerAccess.java Fri May 23 13:38:14 2014 +0200
@@ -134,6 +134,8 @@
* param "port" prints out the port
* nothing or number will run server on random(or on number specified)
* port in -Dtest.server.dir
+ * @param args params from commandline. recognized params are port and randomport
+ * @throws java.lang.Exception if anything happens
*/
public static void main(String[] args) throws Exception {
if (args.length > 0 && args[0].equalsIgnoreCase("port")) {
@@ -212,6 +214,7 @@
/**
*
+ * @param port specific port on which this server is accepting requests
* @return new not cached iserver instance on random port,
* useful for testing application loading from different url then base
*/
@@ -226,6 +229,8 @@
/**
*
+ * @param dir directory from which server returns resources
+ * @param port specific port on which this server is accepting requests
* @return new not cached iserver instance on random port upon custom www root directory,
* useful for testing application loading from different url then base
*/
@@ -342,7 +347,9 @@
/**
*
- * @return url pointing to cached server resource. If non singleton instance is running, new is created.
+ * @throws java.net.MalformedURLException if url for this resource can not be constructed
+ * @return complete url for this resource on this server
+ * @param resource relative path pointing to server resource. If non singleton instance is running, new is created.
*/
public URL getUrl(String resource) throws MalformedURLException {
if (server == null) {
@@ -355,6 +362,7 @@
/**
*
* @return url pointing to cached server . If non singleton instance is running, new is created.
+ * @throws java.net.MalformedURLException
*/
public URL getUrl() throws MalformedURLException {
return getUrl("");
@@ -399,7 +407,7 @@
/**
* utility method which can read bytes of any stream
*
- * @param input stream to be read
+ * @param is stream to be read
* @return individual bytes of resource
* @throws IOException if connection can't be established or resource does not exist
*/
@@ -417,7 +425,8 @@
/**
* utility method which can read from any stream as one long String
*
- * @param input stream
+ * @param is stream to be read
+ * @param encoding encoding of this stream
* @return stream as string
* @throws IOException if connection can't be established or resource does not exist
*/
@@ -428,7 +437,7 @@
/**
* utility method which can read from any stream as one long String
*
- * @param is
+ * @param is input stream to read from
* @return stream as string
* @throws IOException if connection can't be established or resource does not exist
*/
@@ -439,7 +448,7 @@
/**
* utility method which can read bytes of resource from any url
*
- * @param u
+ * @param u full url to read from
* @return individual bytes of resource
* @throws IOException if connection can't be established or resource does not exist
*/
@@ -465,7 +474,7 @@
/**
* utility method which can read string of resource from any url
*
- * @param u
+ * @param u full url to read from
* @return resource as string
* @throws IOException if connection can't be established or resource does
* not exist
@@ -489,15 +498,24 @@
}
/**
- * helping dummy method to save String as file
+ * helping dummy method to save String as file in UTF-8 encoding.
*
- * @param content
- * @param f
+ * @param content which will be saved as it is saved in this String
+ * @param f file to be saved. No warnings provided
* @throws IOException
*/
public static void saveFile(String content, File f) throws IOException {
FileUtils.saveFile(content, f);
}
+
+ /**
+ * helping dummy method to save String as file in specified encoding/.
+ *
+ * @param content which will be saved as it is saved in this String
+ * @param f file to be saved. No warnings provided
+ * @param encoding of output byte representation
+ * @throws IOException
+ */
public static void saveFile(String content, File f,String encoding) throws IOException {
FileUtils.saveFile(content, f, encoding);
}
@@ -569,14 +587,36 @@
return executeBrowser(string, outClosing, errClosing);
}
-
+ /**
+ *
+ * @param resource relative resource to be opened in browser for current server instance.
+ * @return result of browser run
+ *
+ */
public ProcessResult executeBrowser(String resource) throws Exception {
return executeBrowser(getBrowserParams(), resource);
}
+
+ /**
+ *
+ * @param resource relative resource to be opened in browser for current server instance.
+ * @param stdoutl listener for stdout
+ * @param stderrl listener for stderr
+ * @return result of browser run
+ *
+ */
public ProcessResult executeBrowser(String resource,ContentReaderListener stdoutl,ContentReaderListener stderrl) throws Exception {
return executeBrowser(getBrowserParams(), resource, stdoutl, stderrl);
}
+ /**
+ *
+ * @param resource elative resource to be opened in browser for current server instance.
+ * @param stdoutl listeners for stdout
+ * @param stderrl listeners for stderr
+ * @return result of browser run
+ *
+ */
public ProcessResult executeBrowser(String resource, List<ContentReaderListener> stdoutl, List<ContentReaderListener> stderrl) throws Exception {
return executeBrowser(getBrowserParams(), resource, stdoutl, stderrl);
}
@@ -651,9 +691,10 @@
}
/**
- * Ctreate resource on http, on 'localhost' on port on which this instance is running
- * @param resource
- * @return
+ * Create resource on http, on 'localhost' on port on which this instance is running
+ * @param instance of server to return the resource
More information about the distro-pkg-dev
mailing list