utils/jalopy/docs/misc.html

   1
   2 <!--
   3  * Jalview - A Sequence Alignment Editor and Viewer (Version 2.5)
   4  * Copyright (C) 2011 J Procter, AM Waterhouse, J Engelhardt, LM Lui, G Barton, M Clamp, S Searle
   5  *
   6  * This file is part of Jalview.
   7  *
   8  * Jalview is free software: you can redistribute it and/or
   9  * modify it under the terms of the GNU General Public License
  10  * as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
  11  *
  12  * Jalview is distributed in the hope that it will be useful, but
  13  * WITHOUT ANY WARRANTY; without even the implied warranty
  14  * of MERCHANTABILITY or FITNESS FOR A PARTICULAR
  15  * PURPOSE.  See the GNU General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU General Public License along with Jalview.  If not, see <http://www.gnu.org/licenses/>.
  18 -->
  19     <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
  20   <html><head>
  21       <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
  22    <title>4.3.13.&nbsp;Misc</title><link rel="stylesheet" href="site.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.65.1"><link rel="home" href="manual.html" title="Jalopy User Manual"><link rel="up" href="printer.html" title="4.3.&nbsp;Printer"><link rel="previous" href="sorting.html" title="4.3.12.&nbsp;Sorting"><link rel="next" href="inspector.html" title="4.4.&nbsp;Code Inspector"><link rel="preface" href="dedication.html" title="Dedication"><link rel="preface" href="acknowledge.html" title="Acknowledgements"><link rel="preface" href="introduction.html" title="Introduction"><link rel="part" href="part-core.html" title="Part&nbsp;I.&nbsp;Jalopy core"><link rel="chapter" href="installation.html" title="Chapter&nbsp;1.&nbsp;Installation"><link rel="chapter" href="build.html" title="Chapter&nbsp;2.&nbsp;Building"><link rel="chapter" href="usage.html" title="Chapter&nbsp;3.&nbsp;Usage"><link rel="chapter" href="settings.html" title="Chapter&nbsp;4.&nbsp;Settings"><link rel="part" href="part-plugins.html" title="Part&nbsp;II.&nbsp;Plug-ins"><link rel="chapter" href="plugin-ant.html" title="Chapter&nbsp;5.&nbsp;Ant Plug-in task"><link rel="chapter" href="plugin-console.html" title="Chapter&nbsp;6.&nbsp;Console Application"><link rel="chapter" href="plugin-eclipse.html" title="Chapter&nbsp;7.&nbsp;Eclipse Plug-in"><link rel="chapter" href="plugin-jbuilder.html" title="Chapter&nbsp;8.&nbsp;JBuilder OpenTool"><link rel="chapter" href="plugin-jdev.html" title="Chapter&nbsp;9.&nbsp;JDeveloper Extension"><link rel="chapter" href="plugin-jedit.html" title="Chapter&nbsp;10.&nbsp;jEdit Plug-in"><link rel="chapter" href="plugin-netbeans.html" title="Chapter&nbsp;11.&nbsp;NetBeans/Sun ONE Studio module"><link rel="appendix" href="dependencies.html" title="Appendix&nbsp;A.&nbsp;Library Dependencies"><link rel="appendix" href="license-bsd.html" title="Appendix&nbsp;B.&nbsp;The Jalopy BSD License"><link rel="appendix" href="license-antlr.html" title="Appendix&nbsp;C.&nbsp;ANTLR SOFTWARE RIGHTS"><link rel="appendix" href="license-apache.html" title="Appendix&nbsp;D.&nbsp;The Apache Software License, Version 1.1"><link rel="appendix" href="license-gnu.html" title="Appendix&nbsp;E.&nbsp;GNU GENERAL PUBLIC LICENSE Version 2, June 1991"><link rel="appendix" href="license-gnu-doc.html" title="Appendix&nbsp;F.&nbsp;GNU Free Documentation License Version 1.1, March 2000"><link rel="appendix" href="license-common-public.html" title="Appendix&nbsp;G.&nbsp;Common Public License Version 1.0"><link rel="appendix" href="license-sun-public.html" title="Appendix&nbsp;H.&nbsp;SUN PUBLIC LICENSE Version 1.0"><link rel="index" href="ix01.html" title="Index"><link rel="subsection" href="misc.html#misc-misc" title="4.3.13.1.&nbsp;Misc"><link rel="subsection" href="misc.html#misc-history" title="4.3.13.2.&nbsp;History"><link rel="subsection" href="misc.html#misc-backup" title="4.3.13.3.&nbsp;Backup"><link rel="subsection" href="misc.html#misc-threads" title="4.3.13.4.&nbsp;Threads">
  23       <meta name="description" content="Jalopy Java Source Code Formatter Beautifier Pretty Printer">
  24       <meta http-equiv="pics-label" content='(pics-1.1 "http://www.icra.org/ratingsv02.html" l gen true for "http://jalopy.sf.net" r (cz 1 lz 1 nz 1 oz 1 vz 1) "http://www.rsac.org/ratingsv01.html" l gen true for "http://jalopy.sf.net" r (n 0 s 0 v 0 l 0))'>
  25     </head><body id="toppage" bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table width="700" border="0" cellpadding="0" cellspacing="0" align="left"><tbody><tr><td><table cellpadding="0" cellspacing="0" width="100%" style="border:1px solid #336699"><tbody><tr><td height="16"></td></tr><tr><td bgcolor="#3399cc" height="1"></td></tr><tr style="border:none"><td style="border:none"><table border="0" cellspacing="0" cellpadding="0"><tbody><tr><td class="logo">JALOPY</td><td class="sublogo" valign="bottom">Java Source Code Formatter Beautifier Pretty Printer</td></tr></tbody></table></td></tr><tr><td bgcolor="#3399cc" height="1"></td></tr><tr><td height="10"></td></tr><tr><td bgcolor="#ff8000" height="4"></td></tr><tr><td height="20" bgcolor="#336699" style="color:#ffffff;padding-left:10px"><a href="./index.html" class="navlink">Overview</a> &#149;
  26                     <a href="./download.html" class="navlink">Download</a> &#149;
  27                     <a href="./docs.html" class="navlink">Documentation</a> &#149;
  28                     <a href="./plugins.html" class="navlink">Plug-ins</a> &#149;
  29                     <a href="./links.html" class="navlink">Links</a> &#149;
  30                     <a href="./contact.html" class="navlink">Contact</a></td></tr><tr><td height="1" bgcolor="#ffffff"></td></tr></tbody></table></td></tr><tr valign="top"><td valign="top" bgcolor="#ffffff"><table border="0" cellpadding="0" cellspacing="0" width="100%"><tbody><tr><td height="20" bgcolor="#faebd7" style="padding-left:15px"><a href="./features.html" class="navlink2">Features</a> |
  31                     <a href="./history.html" class="navlink2">History</a> |
  32                     <a href="./manual.html" class="navlink2">Manual</a> |
  33                     <a href="./faq.html" class="navlink2">FAQ</a> |
  34                     <a href="./api/index.html" class="navlink2">Javadoc</a></td></tr><tr><td height="20" bgcolor="#ffffff"></td></tr><tr><td bgcolor="#eeeecc" height="17" align="right" style="font-size:10px;padding-right:3px">
  35                     This page generated: <strong>June 8 2004</strong></td></tr></tbody></table><table border="0" width="100%" cellspacing="0" cellpadding="5"><tr><td><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">4.3.13.&nbsp;Misc</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="sorting.html">Prev</a>&nbsp;</td><th width="60%" align="center">4.3.&nbsp;Printer</th><td width="20%" align="right">&nbsp;<a accesskey="n" href="inspector.html">Next</a></td></tr></table><hr></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="misc"></a>4.3.13.&nbsp;Misc</h3></div></div><div></div></div><p>
  36 Lets you control miscellaneous settings that doesn't fit elsewhere.
  37 </p><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="misc-misc"></a>4.3.13.1.&nbsp;Misc</h4></div></div><div></div></div><div class="itemizedlist"><ul type="disc"><li><p><a name="paren-add"></a>
  38 Insert expression parentheses
  39 </p><a class="indexterm" name="d0e4907"></a><a class="indexterm" name="d0e4912"></a><p>
  40 It is always good advise to use more parentheses than you think you need. They
  41 may not be needed, but they add clarity and don't cost anything.
  42 </p><div class="example"><a name="ex-misc-expr"></a><p class="title"><b>Example&nbsp;4.150.&nbsp;How is this expression evaluated?</b></p><table border="0" bgcolor="#E0E0E0" class="shade"><tr><td><pre class="programlisting">
  43 int result = 12 + 4 % 3 * 7 / 8;
  44 </pre></td></tr></table></div><p></p><div class="example"><a name="ex-misc-expr-continued"></a><p class="title"><b>Example&nbsp;4.151.&nbsp;How is this expression evaluated? (continued)</b></p><table border="0" bgcolor="#E0E0E0" class="shade"><tr><td><pre class="programlisting">
  45 int result = 12 + ((4 % 3 * 7) / 8);
  46 </pre></td></tr></table></div><p></p></li><li><p><a name="misc-insert-uid"></a>
  47 Insert serial version UID
  48 </p><a class="indexterm" name="d0e4932"></a><p>
  49 Common sense dictates to declare an explicit serial version UID in every
  50 serializable class to eliminate the serial version UID as a potential source
  51 of incompatibility (with the additional benefit of a small performance gain).
  52 If this switch is enabled and the class directly dereives from either
  53 <tt class="filename">java.io.Serializable</tt> or <tt class="filename">java.io.Externalizable</tt>,
  54 Jalopy computes and inserts a serial version UID for the class.
  55 </p><p>
  56 For this feature to work, the class that has its serial version UID computed
  57 needs to be available on the classpath.
  58 </p></li><li><p><a name="misc-logging-conditional"></a>
  59 Insert logging conditional
  60 </p><p>
  61 Typically, logging systems have a method that submits a logging message like
  62
  63 </p><table border="0" bgcolor="#E0E0E0" class="shade"><tr><td><pre class="screen">
  64 logger.debug("some message: " + someVar);
  65 </pre></td></tr></table><p>
  66 </p><p>
  67 This is fine, but if the debug level is set such that this message will
  68 <span class="emphasis"><em>NOT</em></span> display, then time is wasted doing the string marshalling.
  69 </p><p>
  70 Thus, the preferred way to do this is
  71
  72 </p><table border="0" bgcolor="#E0E0E0" class="shade"><tr><td><pre class="screen">
  73 if (logger.isDebugEnabled()) {
  74     logger.debug("some message: " + someVar);
  75 }
  76 </pre></td></tr></table><p>
  77
  78 which will only use CPU time if the log message is needed. Enabling this switch
  79 will ensure that every logging call with the debug level set will be enclosed with
  80 the conditional expression.
  81 </p><p>
  82 Use this feature with care! The current implementation only supports the Jakarta
  83 Log4J toolkit and is somewhat weak in that every method call called
  84 <i class="firstterm">debug</i> is treated as a logging call which could be incorrect
  85 in your application. However, it works fine for the <i class="firstterm">l7dlog</i> calls.
  86 </p></li><li><p><a name="misc-trailing-newline"></a>
  87 Insert trailing newline
  88 </p><p>
  89 If enabled, Jalopy inserts an empty line at the end of every file. This may
  90 help to avoid problems with certain text formatters and processors.
  91 </p><p>
  92 Note that Jalopy always inserts at least one empty line after footers, so there
  93 is no real need (but it doesn't hurt) to check the mark in case footer insertion
  94 will be performed (see <a href="footer.html" title="4.3.11.&nbsp;Footer">Section&nbsp;4.3.11, &#8220;Footer&#8221;</a>)
  95 </p></li><li><p><a name="misc-array-brackets"></a>
  96 Array brackets after identifiers
  97 </p><p>
  98 Lets you choose where the brackets of array types should be placed.
  99 </p><p>
 100 By default, Jalopy prints the square brackets right after the array type.
 101 </p><div class="example"><a name="ex-misc-array-brackets"></a><p class="title"><b>Example&nbsp;4.152.&nbsp;Array brackets after type</b></p><table border="0" bgcolor="#E0E0E0" class="shade"><tr><td><pre class="programlisting">
 102 int[] a;
 103 </pre></td></tr></table></div><p>
 104 But C/C++ programmers may expect them to appear after the identifier.
 105 </p><div class="example"><a name="ex-misc-array-brackets-identifier"></a><p class="title"><b>Example&nbsp;4.153.&nbsp;Array brackets after identifier</b></p><table border="0" bgcolor="#E0E0E0" class="shade"><tr><td><pre class="programlisting">
 106 int a[];
 107 </pre></td></tr></table></div><p></p></li><li><p>
 108 Force formatting
 109 </p><p>
 110 Jalopy can keep track of which files have been formatted previously.
 111 See <a href="misc.html#misc-history" title="4.3.13.2.&nbsp;History">Section&nbsp;4.3.13.2, &#8220;History&#8221;</a> below. If History is enabled, Jalopy will
 112 exclude files that have a modification date coincident with the last formatting.
 113 However, you can override this history check to force a format. For example,
 114 you might need to update the copyright notice for the whole code base. Enabling
 115 this switch ensures that all source files are always be formatted. Note that
 116 this switch is only meaningful if the history feature is enabled.
 117 </p></li></ul></div></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="misc-history"></a>4.3.13.2.&nbsp;History</h4></div></div><div></div></div><a class="indexterm" name="d0e5010"></a><p>
 118 The history feature offers a way to optimize the speed at which Jalopy processes
 119 of a group of files repeatedly. Using history, Jalopy is able to track file
 120 modifications between successive invocations, and only format those source
 121 files which have actually changed, or which weren't processed previously.
 122 This can save a huge amount of execution time for a project that is formatted
 123 repeatedly over time. There are two methods for keeping history.
 124 </p><div class="itemizedlist"><ul type="disc"><li><p><a name="history-file"></a>
 125 Use history file
 126 </p><a class="indexterm" name="d0e5019"></a><a class="indexterm" name="d0e5024"></a><p>
 127 If you can't get along with a history header comment at the top of each source
 128 file, but would like historical optimization, the file-based approach may work
 129 for you. The history information of previous formatting will be saved in a file
 130 <tt class="filename">history.dat</tt> under the Jalopy settings directory.
 131 </p><p>
 132 Note that this file will grow over time, especially if one manages several big
 133 projects. So the history file could become quite huge. As all history entries
 134 are read into memory at startup, it could eat up quite a bit of memory space.
 135 Therefore a little history viewer is provided which enables you to selectively
 136 remove obsolete entries.
 137 </p><p>
 138 In order to effectively use formatting of a project with several developers it is
 139 nice to be able to only format files which have changed. There are three methods of
 140 working out if a file has changed provided in a drop down. Timestamp will use the
 141 modification time of the file, this does not work very well with source control
 142 and multiple developers. There are two standard checksums available. These
 143 work by taking a checksum of the file and comparing it to the one in the history file.
 144 If this checksum is different, the file is parsed and formatted in memory and a new
 145 checksum calculated. If the new checksum is different than the checksum for the
 146 unformatted file, it is written to disk. This stops files that have just been updated
 147 from source control from having being formatted (and timestamps updated).
 148 </p><p>
 149 Use the <span><b class="guibutton">View...</b></span> button to display the history viewer. You
 150 can selectively remove entries via the popup menu.
 151 </p></li><li><p><a name="history-comment"></a>
 152 Use history comments
 153 </p><a class="indexterm" name="d0e5044"></a><a class="indexterm" name="d0e5049"></a><a class="indexterm" name="d0e5054"></a><p>
 154 Jalopy will insert a small comment in the first line of every source file.
 155 The comment encodes the time a file was last formatted along with the package
 156 name of the file. This method is precise and relatively foolproof but does not work well
 157 with SCM tools.
 158 </p></li></ul></div></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="misc-backup"></a>4.3.13.3.&nbsp;Backup</h4></div></div><div></div></div><p>
 159 For security reasons Jalopy creates a backup copy of the currently
 160 processed file so it can be restored in case a severe error occured during the
 161 formatting process. The original file is stored in the backup directory and normally
 162 deleted after the newly formatted file has been successfully written.
 163 </p><div class="itemizedlist"><ul type="disc"><li><p>
 164 Level
 165 </p><p>
 166 The backup level defines how many numbered backups should be retained (up to 30).
 167 The default is to never hold any backups.
 168 </p></li><li><p>
 169 Directory
 170 </p><p>
 171 Specifies where file backups are stored. You should leave this setting untouched
 172 in order to make your code convention portable across different systems and platforms.
 173 </p></li></ul></div></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="misc-threads"></a>4.3.13.4.&nbsp;Threads</h4></div></div><div></div></div><p>
 174 Jalopy, more precisely the provided Plug-ins, are multi-threaded. On
 175 multi-processor systems the work can be divided onto several processors to
 176 speed up processing.
 177 </p><div class="itemizedlist"><ul type="disc"><li><p>
 178 Number
 179 </p><p>
 180 Specifies the number of processing threads to be used. This setting should be
 181 equal to the number of processors your system has.
 182 </p></li></ul></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sorting.html">Prev</a>&nbsp;</td><td width="20%" align="center"><a accesskey="u" href="printer.html">Up</a></td><td width="40%" align="right">&nbsp;<a accesskey="n" href="inspector.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">4.3.12.&nbsp;Sorting&nbsp;</td><td width="20%" align="center"><a accesskey="h" href="manual.html">Home</a></td><td width="40%" align="right" valign="top">&nbsp;4.4.&nbsp;Code Inspector</td></tr></table></div></td></tr></table></td></tr><tr><td bgcolor="#eeeecc" height="17" style="font-size:9px;padding-left:5px"><a href="#toppage">to top</a></td></tr><tr><td height="30"><br></td></tr><tr><td height="3"></td></tr><tr><td bgcolor="#336699" height="1"></td></tr><tr><td height="1"></td></tr><tr><td bgcolor="#336699" height="16"></td></tr><tr><td bgcolor="#ff9966" height="4"></td></tr><tr><td class="footer" align="center" height="15" valign="middle">
 183             Copyright &copy; 2001-2004, <a class="footer" href="./contact.html">Marco Hunsicker</a>. All rights reserved. Hosted by <a href="http://sourceforge.net">SourceForge.net</a></td></tr></tbody></table><img src="http://sourceforge.net/sflogo.php?group_id=45216&amp;type=1" width="1" height="1" border="0" hspace="0" vspace="0" alt=""></body></html>