Serge NOEL
93 lines
4.0 KiB
Plaintext
93 lines
4.0 KiB
Plaintext
<!DOCTYPE html>
|
|
<html lang="en">
|
|
<head>
|
|
<meta name="generator" content="HTML Tidy for HTML5 for Apple macOS version 5.8.0">
|
|
<title>JMRI: Portable File Access</title>
|
|
<meta name="author" content="Bob Jacobsen">
|
|
<meta name="keywords" content="JMRI technical code portable file location">
|
|
<!-- The combination of "Define" and {Header,Style, Logo and Footer} comments -->
|
|
<!-- are an arbitrary design pattern used by the update.pl script to -->
|
|
<!-- easily replace the common header/footer code for all the web pages -->
|
|
<!-- delete the following 2 Defines if you want to use the default JMRI logo -->
|
|
<!-- or change them to reflect your alternative logo -->
|
|
<!--#include virtual="/help/en/parts/Style.shtml" -->
|
|
</head>
|
|
<body>
|
|
<!--#include virtual="/help/en/parts/Header.shtml" -->
|
|
|
|
<div id="mBody">
|
|
<!--#include virtual="Sidebar.shtml" -->
|
|
|
|
<div id="mainContent">
|
|
<h1>JMRI Code: Portable File Access</h1>
|
|
|
|
<p>JMRI uses files for icons, images, panel files, scripts, and lots of other things.
|
|
References to those are routinely used by various code, and stored in XML files. Some of the
|
|
files are distributed with JMRI, and some are created outside the JMRI distribution directory
|
|
by the local user.</p>
|
|
|
|
<p>In addition, JMRI is a cross-platform application, and we want to be able to move JMRI XML
|
|
files from one computer to another, even of a different type, and have them still work.</p>
|
|
|
|
<p>To do this, we've created a system of pseudo-URLs for accessing file locations. Filenames
|
|
are used internally and stored in XML files with prefixes that identify where the file is to
|
|
be found in a system independent manner.</p>
|
|
|
|
<dl>
|
|
<dt>program:</dt>
|
|
|
|
<dd>Treats the path as a relative path below the JMRI installation directory. In JMRI
|
|
2.13.1 and earlier, this was the <code>resources:</code> prefix.</dd>
|
|
|
|
<dt>preference:</dt>
|
|
|
|
<dd>Treats the path as a relative path below the user files (or preferences) directory. In
|
|
JMRI 2.13.1 and earlier, thie was the <code>file:</code> prefix.</dd>
|
|
|
|
<dt>profile:</dt>
|
|
|
|
<dd>Treats the path as a relative path below the configuration profile directory.</dd>
|
|
|
|
<dt>settings:</dt>
|
|
|
|
<dd>Treats the path as a relative path below the settings directory (the directory where
|
|
per-computer preferences are stored).</dd>
|
|
|
|
<dt>home:</dt>
|
|
|
|
<dd>Treats the path as a relative path below the user's home directory.</dd>
|
|
</dl>
|
|
Otherwise, treat the name as a relative path below the program directory to provide backward
|
|
compatibility. In any case, absolute pathnames will work, but won't be cross-platform
|
|
compatible.
|
|
<h2>Implementation</h2>
|
|
The <a href="https://jmri.org/JavaDoc/doc/jmri/util/FileUtil.html">jmri.util.FileUtil</a>
|
|
class provides translation routines to make this automatic:
|
|
<dl>
|
|
<dd>static public String getExternalFilename(String pName)</dd>
|
|
|
|
<dt>Convert an internal name (with prefixes as above) into an absolute pathname for use on
|
|
the local computer. There's no guarantee that the file or any enclosing directory is
|
|
actually present, but the pathname will be syntactically valid on the present
|
|
computer.</dt>
|
|
|
|
<dd>static public String getPortableFilename(File file)</dd>
|
|
|
|
<dd>static public String getPortableFilename(String filename)</dd>
|
|
|
|
<dt>Convert a File or filename string into a string name with the appropriate prefix.</dt>
|
|
</dl>
|
|
|
|
<p>You should call getExternalFilename() before passing the filename to any Java common, and
|
|
getPortableFilename() whenever you get a file or filename from a Java class. It's OK to call
|
|
either one multiple times, as they'll just pass through in that case. In particular, call
|
|
getPortableFilename() before storing to an XML file.</p>
|
|
<!--#include virtual="/help/en/parts/Footer.shtml" -->
|
|
</div>
|
|
<!-- closes #mainContent-->
|
|
</div>
|
|
<!-- closes #mBody-->
|
|
<script src="/js/help.js"></script>
|
|
</body>
|
|
</html>
|