com.github.aliteralmind.codelet.util

Class OnlineOfflineDocRoot

java.lang.Object

com.github.xbn.keyed.SimpleKeyed<String>

com.github.xbn.keyed.SimpleNamed

com.github.aliteralmind.codelet.util.OnlineOfflineDocRoot

All Implemented Interfaces:

Keyed<String>, Named

public class OnlineOfflineDocRoot
extends SimpleNamed

Represents the package-list for a single external Java library, including a duplicate offline file that is automatically updated from it.

Since:

0.1.0

Author:

Copyright (C) 2014, Jeff Epstein (aliteralmind __DASH__ github __AT__ yahoo __DOT__ com), dual-licensed under the LGPL (version 3.0 or later) or the ASL (version 2.0). See source code for details. http://codelet.aliteralmind.com, https://github.com/aliteralmind/codelet

Constructor Summary

Constructors

Constructor and Description
OnlineOfflineDocRoot(String name, String url_toDocRoot, String offline_path, List<String> package_list) Create a new instance from a url, offline path, and package list.

Method Summary

Methods

Modifier and Type	Method and Description
StringBuilder	appendToString(StringBuilder to_appendTo)
List<String>	getPackageList() An immutable list of all package names.
String	getPath() Full path to the offline duplicate of the package-list file.
String	getUrlDir() Url of the directory in which the package-list file exists.
static OnlineOfflineDocRoot	newFromOffline(String name, String url_toDocRoot, String offline_path, Appendable debug_ifNonNull, Appendable dbgError_ifNonNull) Create a new instance from an offline package-list.
static OnlineOfflineDocRoot	newFromOnline(String name, String url_toDocRoot, String offline_path, int error_attemptCount, long error_sleepMills, IfError if_error, RefreshOffline refresh_offline, Appendable debug_ifNonNull, Appendable dbgError_ifNonNull) Create a new instance from an online package-list.
static List<String>	newPackageListFromOffline(String pkgList_path, Appendable debug_ifNonNull, Appendable dbgError_ifNonNull) Create a package list from an offline package-list file.
static List<String>	newPackageListFromOnline(String url_toDocRoot, int error_attemptCount, long error_sleepMills, IfError if_error, Appendable debug_ifNonNull, Appendable dbgError_ifNonNull) Create a package list from an online package-list.
void	refreshOffline(Appendable debug_ifNonNull, Appendable dbgError_ifNonNull) Overwrites or creates offline file with the current package list.
String	toString()

Methods inherited from class com.github.xbn.keyed.SimpleNamed

ciBadNameInCnstr, getName

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

OnlineOfflineDocRoot

public OnlineOfflineDocRoot(String name,
                    String url_toDocRoot,
                    String offline_path,
                    List<String> package_list)

Create a new instance from a url, offline path, and package list.

Parameters:

name - Descriptive name of the external library. May not be null or empty, and must contain only letters, digits, and underscores. Get with getName()*

url_toDocRoot - The url directory in which the package-list file exists. Should be a valid url and end with a slash ('/'). Get with getUrlDir().

offline_path - The full path of the offline duplicate of the package-list file. Should be a valid represent a text file that is both readable and writable. Get with getPath()

package_list - The list of packages in the external library, as found in package-list. May not be null, empty, and its elements may not be null, empty, or duplicate. Get (a duplicate of this list) with getPackageList().

See Also:

newFromOnline, newFromOffline

Method Detail

getUrlDir

public String getUrlDir()

Url of the directory in which the package-list file exists.

Returns:

A non-null url, ending with a slash ('/').

See Also:

getPath()

getPath

public String getPath()

Full path to the offline duplicate of the package-list file.

Returns:

A non-null path, including the file-name.

See Also:

getUrlDir()

getPackageList

public List<String> getPackageList()

An immutable list of all package names.

refreshOffline

public void refreshOffline(Appendable debug_ifNonNull,
                  Appendable dbgError_ifNonNull)

Overwrites or creates offline file with the current package list.

This overwrites the current offline file with the contents of the package list.

Parameters:

debug_ifNonNull - If non-null, the destination for progress debugging.

dbgError_ifNonNull - If non-null, the destination for the error debugging. If if_error.WARN, this parameter may not be null.

Throws:

RTFileNotFoundException - If a FileNotFoundException is thrown when trying to open the file. The original exception (for this and all exceptions thrown by this function) is accessible with getCause().

RTIOException - If an IOException is thrown when trying to open the file.

SecurityException - If the file is not writable.

RuntimeException - If the file is successfully opened, but cannot be written to.

See Also:

getPackageList()

toString

public String toString()

Overrides:

toString in class SimpleKeyed<String>

Returns:

appendToString(new StringBuilder()).toString()

appendToString

public StringBuilder appendToString(StringBuilder to_appendTo)

Parameters:

to_appendTo - May not be null.

See Also:

toString()

newFromOnline

public static final OnlineOfflineDocRoot newFromOnline(String name,
                                 String url_toDocRoot,
                                 String offline_path,
                                 int error_attemptCount,
                                 long error_sleepMills,
                                 IfError if_error,
                                 RefreshOffline refresh_offline,
                                 Appendable debug_ifNonNull,
                                 Appendable dbgError_ifNonNull)
                                                throws InterruptedException

Create a new instance from an online package-list.

Parameters:

refresh_offline - If YES, then this ends by calling
[the-new-OnlineOfflineDocRoot].refreshOffline(debug_ifNonNull, dbgError_ifNonNull)
This parameter may not be null.

Returns:

new OnlineOfflineDocRoot(url_toDocRoot, offline_path,
newPackageListFromOnline(offline_path,
error_attemptCount, error_sleepMills, if_error, debug_ifNonNull, dbgError_ifNonNull))
If the package list cannot be retrieved, and if_error.com.github.xbn.util.IfError#WARN WARN, this returns null.

Throws:

InterruptedException

See Also:

newFromOffline

newFromOffline

public static final OnlineOfflineDocRoot newFromOffline(String name,
                                  String url_toDocRoot,
                                  String offline_path,
                                  Appendable debug_ifNonNull,
                                  Appendable dbgError_ifNonNull)

Create a new instance from an offline package-list.

Returns:

new OnlineOfflineDocRoot(url_toDocRoot, offline_path,
newPackageListFromOnline(offline_path, if_error, debug_ifNonNull, dbgError_ifNonNull))

See Also:

newFromOnline

newPackageListFromOffline

public static final List<String> newPackageListFromOffline(String pkgList_path,
                                     Appendable debug_ifNonNull,
                                     Appendable dbgError_ifNonNull)

Create a package list from an offline package-list file.

Parameters:

pkgList_path - The full path to the local package-list file. Must represent a file that is readable and writable (writability is not verified until the offline file is refreshed), and a valid package-list.

debug_ifNonNull - If non-null, the destination for progress debugging.

dbgError_ifNonNull - If non-null, the destination for the error debugging.

Throws:

RuntimeException - If opening or reading the file fails. The original exception is accessible with getCause().

See Also:

newFromOffline, newPackageListFromOnline

newPackageListFromOnline

public static final List<String> newPackageListFromOnline(String url_toDocRoot,
                                    int error_attemptCount,
                                    long error_sleepMills,
                                    IfError if_error,
                                    Appendable debug_ifNonNull,
                                    Appendable dbgError_ifNonNull)
                                                   throws InterruptedException

Create a package list from an online package-list.

Parameters:

url_toDocRoot - The url directory in which a valid package-list file exists. Must end with a slash ('/').

error_attemptCount - The number of attempts to make when retrieving the package-list fails. May not be less than one.

error_sleepMills - The number of milliseconds to sleep between each attempt. May not be less than zero.

if_error - If WARN then, after all attempts fail, the error is logged to dbgError_ifNonNull. If CRASH a RuntimeException is also thrown. This parameter may not be null.

dbgError_ifNonNull - The destination for the error-warning message. If if_error.WARN, may not be null.

Returns:

If the package-list

• Was successfully retrieved: A non-null list containing all its packages.
• Could not be retrieved and if_error.WARN: null

Throws:

RuntimeException - If any error occurs when retrieving the package-list. The causing error is accessible with getCause().

RTIOException - If using dbgError_ifNonNull fails.

InterruptedException

See Also:

newFromOnline, newPackageListFromOffline