Coverage Report

Coverage Report - org.crosswire.common.util.CWProject

Classes in this File

Line Coverage

Branch Coverage

Complexity

CWProject

0/72

0/34

2.571

 /**
  * Distribution License:
  * JSword is free software; you can redistribute it and/or modify it under
  * the terms of the GNU Lesser General Public License, version 2.1 or later
  * as published by the Free Software Foundation. This program is distributed
  * in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even
  * the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
  * See the GNU Lesser General Public License for more details.
  *
  * The License is available on the internet at:
  *      http://www.gnu.org/copyleft/lgpl.html
  * or by writing to:
  *      Free Software Foundation, Inc.
  *      59 Temple Place - Suite 330
  *      Boston, MA 02111-1307, USA
  *
  * © CrossWire Bible Society, 2008 - 2016
  *
  */
 package org.crosswire.common.util;
 
 import java.io.File;
 import java.io.IOException;
 import java.net.URI;
 
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
 /**
  * The Project class looks after the source of project files. These are per user
  * files and as such have a different location on different operating systems.
  * These are:<br>
  * 
  * <table>
  * <tr>
  * <td>Mac OS X</td>
  * <td>~/Library/Application Support/JSword</td>
  * </tr>
  * <tr>
  * <td>Win NT/2000/XP/ME/9x</td>
  * <td>~/Application Data/JSword (~ is all over the place, but Java figures it
  * out)</td>
  * </tr>
  * <tr>
  * <td>Unix and otherwise</td>
  * <td>~/.jsword</td>
  * </tr>
  * </table>
  * 
  * <p>
  * Previously the location was ~/.jsword, which is unfriendly in the Windows and
  * Mac world. If this location is found on Mac or Windows, it will be moved to
  * the new location, if different and possible.
  * </p>
  * 
  * <p>
  * Note: If the Java System property jsword.home is set and it exists and is
  * writable then it will be used instead of the above location. This is useful
  * for USB Drives and other portable implementations of JSword. It is
  * recommended that this name be JSword.
  * </p>
  * 
  * @see gnu.lgpl.License The GNU Lesser General Public License for details.
  * @author DM Smith
  */
 public final class CWProject {
     /**
      * Accessor for the resource singleton.
      * 
      * @return the singleton
      */
     public static CWProject instance() {
         return instance;
     }
 
     /**
      * Required for reset of statics during testing
      */
     @SuppressWarnings("unused")
     private static void reset() {
         instance = new CWProject();
     }
 
     /**
      * Establish how this project finds it's resources.
      * 
      * @param homeProperty
      *            a property that is used as the home directory name. If this
      *            property has a value then homeDir and altHomeDir are ignored.
      *            Defaults to jsword.home.
      * @param homeDir
      *            the name of the directory to be used for Unix. Typically this
      *            is a hidden directory, that is, it begins with a '.'. Defaults
      *            to .jsword
      * @param altHomeDir
      *            the name of the directory to be used for other OSes. This
      *            should not be a hidden directory. Defaults to JSword.
      */
     public static void setHome(String homeProperty, String homeDir, String altHomeDir) {
         CWProject.homeProperty = homeProperty;
         CWProject.homeDirectory = homeDir;
         CWProject.homeAltDirectory = altHomeDir;
         instance().establishProjectHome();
     }
 
     /**
      * Sets the name of the front-end. This then informs the read/write directory of the front-end.
      * @param frontendName
      */
     public void setFrontendName(String frontendName) {
         this.frontendName = frontendName;
     }
 
     /**
      * @return the writable home for the front-end settings, that can be kept separate from JSword's
      * configuration, as well from other front-ends.
      */
     public URI getWritableFrontendProjectDir() {
         establishProjectHome();
         return this.writableFrontEndHome;
     }
 
     /**
      * @return the readable home for the front-end settings, that can be kept separate from JSword's
      * configuration, as well from other front-ends.
      */
     public URI getReadableFrontendProjectDir() {
         establishProjectHome();
         return this.frontendReadHome;
     }
 
 
     /**
      * Get the writable user project directory.
      * 
      * @return the writable user project directory.
      */
     public URI getWritableProjectDir() {
         establishProjectHome();
         return writeHome;
     }
 
     /**
      * Get the locations where project resources can be found.
      * 
      * @return an array of URIs which can be used to look up resources.
      */
     public URI[] getProjectResourceDirs() {
         establishProjectHome();
         return homes.clone();
     }
 
     /**
      * Get the location where the project directory used to be.
      * 
      * @return ~/.jsword
      */
     public URI getDeprecatedWritableProjectDir() {
         return OSType.DEFAULT.getUserAreaFolder(homeDirectory, homeAltDirectory);
     }
 
     /**
      * Create a the URI for a (potentially non-existent) file to which we can
      * write. Typically this is used to store user preferences and application
      * overrides. This method of acquiring files is preferred over
      * getResourceProperties() as this is writable and can take into account
      * user preferences. This method makes no promise that the URI returned is
      * valid. It is totally untested, so reading may well cause errors.
      * 
      * @param subject
      *            The name (minus the .xxx extension)
      * @param extension
      *            The extension, prefixed with a '.' See: {@link FileUtil} for a
      *            list of popular extensions.
      * @return The resource as a URI
      */
     public URI getWritableURI(String subject, String extension) {
         return NetUtil.lengthenURI(getWritableProjectDir(), subject + extension);
     }
 
     /**
      * A directory within the project directory.
      * 
      * @param subject
      *            A name for the subdirectory of the Project directory.
      * @param create whether to create the directory if it does not exist
      * @return A file: URI pointing at a local writable directory.
      * @throws IOException 
      */
     public URI getWritableProjectSubdir(String subject, boolean create) throws IOException {
         URI temp = NetUtil.lengthenURI(getWritableProjectDir(), subject);
 
         if (create && !NetUtil.isDirectory(temp)) {
             NetUtil.makeDirectory(temp);
         }
 
         return temp;
     }
 
     /**
      * Prevent instantiation.
      */
     private CWProject() {
     }
 
     /**
      * Establishes the user's project directory. In a CD installation, the home
      * directory on the CD will be read-only. This is not sufficient. We also
      * need a writable home directory. And in looking up resources, the ones in
      * the writable directory trump those in the readable directory, allowing
      * the read-only resources to be overridden.
      * <p>
      * Here is the lookup order:
      * <ol>
      * <li>Check first to see if the jsword.home property is set.</li>
      * <li>Check for the existence of a platform specific project area and for
      * the existence of a deprecated project area (~/.jsword on Windows and Mac)
      * and if it exists and it is possible "upgrade" to the platform specific
      * project area. Of these "two" only one is the folder to check.</li>
      * </ol>
      * In checking these areas, if the one is read-only, add it to the list and
      * keep going. However, if it is also writable, then use it alone.
      */
     private void establishProjectHome() {
         if (writeHome == null && readHome == null) {
             // if there is a property set for the jsword home directory
             String cwHome = System.getProperty(homeProperty);
             if (cwHome != null) {
                 URI home = NetUtil.getURI(new File(cwHome));
                 if (NetUtil.canWrite(home)) {
                     writeHome = home;
                 } else if (NetUtil.canRead(home)) {
                     readHome = home;
                 }
                 // otherwise jsword.home is not usable.
             }
         }
 
         if (writeHome == null) {
             URI path = OSType.getOSType().getUserAreaFolder(homeDirectory, homeAltDirectory);
             URI oldPath = getDeprecatedWritableProjectDir();
             writeHome = migrateUserProjectDir(oldPath, path);
         }
 
         if (homes == null) {
             if (readHome == null) {
                 homes = new URI[] {
                     writeHome
                 };
             } else {
                 homes = new URI[] {
                         writeHome, readHome
                 };
             }
 
             // Now that we know the "home" we can set other global notions of home.
             // TODO(dms): refactor this to CWClassLoader and NetUtil.
             CWClassLoader.setHome(getProjectResourceDirs());
 
             try {
                 URI uricache = getWritableProjectSubdir(DIR_NETCACHE, true);
                 File filecache = new File(uricache.getPath());
                 NetUtil.setURICacheDir(filecache);
             } catch (IOException ex) {
                 // This isn't fatal, it just means that NetUtil will try to use $TMP
                 // in place of a more permanent solution.
                 LOGGER.warn("Failed to get directory for NetUtil.setURICacheDir()", ex);
             }
 
             //also attempt to create the front-end home
             try {
                 if (this.frontendName != null) {
                     this.writableFrontEndHome = getWritableProjectSubdir(this.frontendName, true);
                 }
             } catch (IOException ex) {
                 LOGGER.warn("Failed to create writable front-end home.", ex);
             }
 
             //attempt to set front-end readable home, if different
             if (readHome != null && this.frontendName != null) {
                 this.frontendReadHome = NetUtil.lengthenURI(this.readHome, this.frontendName);
             }
         }
     }
 
     /**
      * Migrates the user's project dir, if necessary and possible.
      * 
      * @param oldPath
      *            the path to the old, deprecated location
      * @param newPath
      *            the path to the new location
      * @return newPath if the migration was possible or not needed.
      */
     private URI migrateUserProjectDir(URI oldPath, URI newPath) {
         if (oldPath.toString().equals(newPath.toString())) {
             return newPath;
         }
 
         if (NetUtil.isDirectory(oldPath)) {
             File oldDir = new File(oldPath.getPath());
             File newDir = new File(newPath.getPath());
 
             // renameTo will return false if it could not rename.
             // This will happen if the directory already exists.
             // So ensure that the directory does not currently exist.
             if (!NetUtil.isDirectory(newPath)) {
                 if (oldDir.renameTo(newDir)) {
                     return newPath;
                 }
                 return oldPath;
             }
         }
         return newPath;
     }
 
     /**
      * The cache of downloaded files inside the project directory
      */
     private static final String DIR_NETCACHE = "netcache";
 
     /**
      * The homes for this application: first is writable, second (if present) is
      * read-only and specified by the system property jsword.home.
      */
     private URI[] homes;
 
     /**
      * The writable home for this application.
      */
     private URI writeHome;
 
     /**
      * The name of the front-end application. This allows front-ends to store information
      * under the jsword directory, separate from other front-ends
      */
     private String frontendName;
 
     /**
      * The readable home for this application, specified by the system property
      * jsword.home. Null, if jsword.home is also writable.
      */
     private URI readHome;
 
     /**
      * Front-end home, where the app can write information to it. Could be null if failed to create
      */
     private URI writableFrontEndHome;
 
     /**
      * Front-end read home, could be null if not present
      */
     private URI frontendReadHome;
 
     /**
      * System property for home directory
      */
     private static String homeProperty = "jsword.home";
 
     /**
      * The JSword user settings directory
      */
     private static String homeDirectory = ".jsword";
 
     /**
      * The JSword user settings directory for Mac and Windows
      */
     private static String homeAltDirectory = "JSword";
 
     /**
      * The filesystem resources
      */
     private static CWProject instance = new CWProject();
 
     /**
      * The log stream
      */
     private static final Logger LOGGER = LoggerFactory.getLogger(CWProject.class);
 }

1		/**
2		* Distribution License:
3		* JSword is free software; you can redistribute it and/or modify it under
4		* the terms of the GNU Lesser General Public License, version 2.1 or later
5		* as published by the Free Software Foundation. This program is distributed
6		* in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even
7		* the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
8		* See the GNU Lesser General Public License for more details.
9		*
10		* The License is available on the internet at:
11		* http://www.gnu.org/copyleft/lgpl.html
12		* or by writing to:
13		* Free Software Foundation, Inc.
14		* 59 Temple Place - Suite 330
15		* Boston, MA 02111-1307, USA
16		*
17		* © CrossWire Bible Society, 2008 - 2016
18		*
19		*/
20		package org.crosswire.common.util;
21
22		import java.io.File;
23		import java.io.IOException;
24		import java.net.URI;
25
26		import org.slf4j.Logger;
27		import org.slf4j.LoggerFactory;
28
29		/**
30		* The Project class looks after the source of project files. These are per user
31		* files and as such have a different location on different operating systems.
32		* These are:<br>
33		*
34		* <table>
35		* <tr>
36		* <td>Mac OS X</td>
37		* <td>~/Library/Application Support/JSword</td>
38		* </tr>
39		* <tr>
40		* <td>Win NT/2000/XP/ME/9x</td>
41		* <td>~/Application Data/JSword (~ is all over the place, but Java figures it
42		* out)</td>
43		* </tr>
44		* <tr>
45		* <td>Unix and otherwise</td>
46		* <td>~/.jsword</td>
47		* </tr>
48		* </table>
49		*
50		* <p>
51		* Previously the location was ~/.jsword, which is unfriendly in the Windows and
52		* Mac world. If this location is found on Mac or Windows, it will be moved to
53		* the new location, if different and possible.
54		* </p>
55		*
56		* <p>
57		* Note: If the Java System property jsword.home is set and it exists and is
58		* writable then it will be used instead of the above location. This is useful
59		* for USB Drives and other portable implementations of JSword. It is
60		* recommended that this name be JSword.
61		* </p>
62		*
63		* @see gnu.lgpl.License The GNU Lesser General Public License for details.
64		* @author DM Smith
65		*/
66		public final class CWProject {
67		/**
68		* Accessor for the resource singleton.
69		*
70		* @return the singleton
71		*/
72		public static CWProject instance() {
73	0	return instance;
74		}
75
76		/**
77		* Required for reset of statics during testing
78		*/
79		@SuppressWarnings("unused")
80		private static void reset() {
81	0	instance = new CWProject();
82	0	}
83
84		/**
85		* Establish how this project finds it's resources.
86		*
87		* @param homeProperty
88		* a property that is used as the home directory name. If this
89		* property has a value then homeDir and altHomeDir are ignored.
90		* Defaults to jsword.home.
91		* @param homeDir
92		* the name of the directory to be used for Unix. Typically this
93		* is a hidden directory, that is, it begins with a '.'. Defaults
94		* to .jsword
95		* @param altHomeDir
96		* the name of the directory to be used for other OSes. This
97		* should not be a hidden directory. Defaults to JSword.
98		*/
99		public static void setHome(String homeProperty, String homeDir, String altHomeDir) {
100	0	CWProject.homeProperty = homeProperty;
101	0	CWProject.homeDirectory = homeDir;
102	0	CWProject.homeAltDirectory = altHomeDir;
103	0	instance().establishProjectHome();
104	0	}
105
106		/**
107		* Sets the name of the front-end. This then informs the read/write directory of the front-end.
108		* @param frontendName
109		*/
110		public void setFrontendName(String frontendName) {
111	0	this.frontendName = frontendName;
112	0	}
113
114		/**
115		* @return the writable home for the front-end settings, that can be kept separate from JSword's
116		* configuration, as well from other front-ends.
117		*/
118		public URI getWritableFrontendProjectDir() {
119	0	establishProjectHome();
120	0	return this.writableFrontEndHome;
121		}
122
123		/**
124		* @return the readable home for the front-end settings, that can be kept separate from JSword's
125		* configuration, as well from other front-ends.
126		*/
127		public URI getReadableFrontendProjectDir() {
128	0	establishProjectHome();
129	0	return this.frontendReadHome;
130		}
131
132
133		/**
134		* Get the writable user project directory.
135		*
136		* @return the writable user project directory.
137		*/
138		public URI getWritableProjectDir() {
139	0	establishProjectHome();
140	0	return writeHome;
141		}
142
143		/**
144		* Get the locations where project resources can be found.
145		*
146		* @return an array of URIs which can be used to look up resources.
147		*/
148		public URI[] getProjectResourceDirs() {
149	0	establishProjectHome();
150	0	return homes.clone();
151		}
152
153		/**
154		* Get the location where the project directory used to be.
155		*
156		* @return ~/.jsword
157		*/
158		public URI getDeprecatedWritableProjectDir() {
159	0	return OSType.DEFAULT.getUserAreaFolder(homeDirectory, homeAltDirectory);
160		}
161
162		/**
163		* Create a the URI for a (potentially non-existent) file to which we can
164		* write. Typically this is used to store user preferences and application
165		* overrides. This method of acquiring files is preferred over
166		* getResourceProperties() as this is writable and can take into account
167		* user preferences. This method makes no promise that the URI returned is
168		* valid. It is totally untested, so reading may well cause errors.
169		*
170		* @param subject
171		* The name (minus the .xxx extension)
172		* @param extension
173		* The extension, prefixed with a '.' See: {@link FileUtil} for a
174		* list of popular extensions.
175		* @return The resource as a URI
176		*/
177		public URI getWritableURI(String subject, String extension) {
178	0	return NetUtil.lengthenURI(getWritableProjectDir(), subject + extension);
179		}
180
181		/**
182		* A directory within the project directory.
183		*
184		* @param subject
185		* A name for the subdirectory of the Project directory.
186		* @param create whether to create the directory if it does not exist
187		* @return A file: URI pointing at a local writable directory.
188		* @throws IOException
189		*/
190		public URI getWritableProjectSubdir(String subject, boolean create) throws IOException {
191	0	URI temp = NetUtil.lengthenURI(getWritableProjectDir(), subject);
192
193	0	if (create && !NetUtil.isDirectory(temp)) {
194	0	NetUtil.makeDirectory(temp);
195		}
196
197	0	return temp;
198		}
199
200		/**
201		* Prevent instantiation.
202		*/
203	0	private CWProject() {
204	0	}
205
206		/**
207		* Establishes the user's project directory. In a CD installation, the home
208		* directory on the CD will be read-only. This is not sufficient. We also
209		* need a writable home directory. And in looking up resources, the ones in
210		* the writable directory trump those in the readable directory, allowing
211		* the read-only resources to be overridden.
212		* <p>
213		* Here is the lookup order:
214		* <ol>
215		* <li>Check first to see if the jsword.home property is set.</li>
216		* <li>Check for the existence of a platform specific project area and for
217		* the existence of a deprecated project area (~/.jsword on Windows and Mac)
218		* and if it exists and it is possible "upgrade" to the platform specific
219		* project area. Of these "two" only one is the folder to check.</li>
220		* </ol>
221		* In checking these areas, if the one is read-only, add it to the list and
222		* keep going. However, if it is also writable, then use it alone.
223		*/
224		private void establishProjectHome() {
225	0	if (writeHome == null && readHome == null) {
226		// if there is a property set for the jsword home directory
227	0	String cwHome = System.getProperty(homeProperty);
228	0	if (cwHome != null) {
229	0	URI home = NetUtil.getURI(new File(cwHome));
230	0	if (NetUtil.canWrite(home)) {
231	0	writeHome = home;
232	0	} else if (NetUtil.canRead(home)) {
233	0	readHome = home;
234		}
235		// otherwise jsword.home is not usable.
236		}
237		}
238
239	0	if (writeHome == null) {
240	0	URI path = OSType.getOSType().getUserAreaFolder(homeDirectory, homeAltDirectory);
241	0	URI oldPath = getDeprecatedWritableProjectDir();
242	0	writeHome = migrateUserProjectDir(oldPath, path);
243		}
244
245	0	if (homes == null) {
246	0	if (readHome == null) {
247	0	homes = new URI[] {
248		writeHome
249		};
250		} else {
251	0	homes = new URI[] {
252		writeHome, readHome
253		};
254		}
255
256		// Now that we know the "home" we can set other global notions of home.
257		// TODO(dms): refactor this to CWClassLoader and NetUtil.
258	0	CWClassLoader.setHome(getProjectResourceDirs());
259
260		try {
261	0	URI uricache = getWritableProjectSubdir(DIR_NETCACHE, true);
262	0	File filecache = new File(uricache.getPath());
263	0	NetUtil.setURICacheDir(filecache);
264	0	} catch (IOException ex) {
265		// This isn't fatal, it just means that NetUtil will try to use $TMP
266		// in place of a more permanent solution.
267	0	LOGGER.warn("Failed to get directory for NetUtil.setURICacheDir()", ex);
268	0	}
269
270		//also attempt to create the front-end home
271		try {
272	0	if (this.frontendName != null) {
273	0	this.writableFrontEndHome = getWritableProjectSubdir(this.frontendName, true);
274		}
275	0	} catch (IOException ex) {
276	0	LOGGER.warn("Failed to create writable front-end home.", ex);
277	0	}
278
279		//attempt to set front-end readable home, if different
280	0	if (readHome != null && this.frontendName != null) {
281	0	this.frontendReadHome = NetUtil.lengthenURI(this.readHome, this.frontendName);
282		}
283		}
284	0	}
285
286		/**
287		* Migrates the user's project dir, if necessary and possible.
288		*
289		* @param oldPath
290		* the path to the old, deprecated location
291		* @param newPath
292		* the path to the new location
293		* @return newPath if the migration was possible or not needed.
294		*/
295		private URI migrateUserProjectDir(URI oldPath, URI newPath) {
296	0	if (oldPath.toString().equals(newPath.toString())) {
297	0	return newPath;
298		}
299
300	0	if (NetUtil.isDirectory(oldPath)) {
301	0	File oldDir = new File(oldPath.getPath());
302	0	File newDir = new File(newPath.getPath());
303
304		// renameTo will return false if it could not rename.
305		// This will happen if the directory already exists.
306		// So ensure that the directory does not currently exist.
307	0	if (!NetUtil.isDirectory(newPath)) {
308	0	if (oldDir.renameTo(newDir)) {
309	0	return newPath;
310		}
311	0	return oldPath;
312		}
313		}
314	0	return newPath;
315		}
316
317		/**
318		* The cache of downloaded files inside the project directory
319		*/
320		private static final String DIR_NETCACHE = "netcache";
321
322		/**
323		* The homes for this application: first is writable, second (if present) is
324		* read-only and specified by the system property jsword.home.
325		*/
326		private URI[] homes;
327
328		/**
329		* The writable home for this application.
330		*/
331		private URI writeHome;
332
333		/**
334		* The name of the front-end application. This allows front-ends to store information
335		* under the jsword directory, separate from other front-ends
336		*/
337		private String frontendName;
338
339		/**
340		* The readable home for this application, specified by the system property
341		* jsword.home. Null, if jsword.home is also writable.
342		*/
343		private URI readHome;
344
345		/**
346		* Front-end home, where the app can write information to it. Could be null if failed to create
347		*/
348		private URI writableFrontEndHome;
349
350		/**
351		* Front-end read home, could be null if not present
352		*/
353		private URI frontendReadHome;
354
355		/**
356		* System property for home directory
357		*/
358	0	private static String homeProperty = "jsword.home";
359
360		/**
361		* The JSword user settings directory
362		*/
363	0	private static String homeDirectory = ".jsword";
364
365		/**
366		* The JSword user settings directory for Mac and Windows
367		*/
368	0	private static String homeAltDirectory = "JSword";
369
370		/**
371		* The filesystem resources
372		*/
373	0	private static CWProject instance = new CWProject();
374
375		/**
376		* The log stream
377		*/
378	0	private static final Logger LOGGER = LoggerFactory.getLogger(CWProject.class);
379		}