utils/jalopy/docs/misc.html

   1
   2     <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
   3   <html><head>
   4       <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
   5    <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">
   6       <meta name="description" content="Jalopy Java Source Code Formatter Beautifier Pretty Printer">
   7       <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))'>
   8     </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;
   9                     <a href="./download.html" class="navlink">Download</a> &#149;
  10                     <a href="./docs.html" class="navlink">Documentation</a> &#149;
  11                     <a href="./plugins.html" class="navlink">Plug-ins</a> &#149;
  12                     <a href="./links.html" class="navlink">Links</a> &#149;
  13                     <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> |
  14                     <a href="./history.html" class="navlink2">History</a> |
  15                     <a href="./manual.html" class="navlink2">Manual</a> |
  16                     <a href="./faq.html" class="navlink2">FAQ</a> |
  17                     <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">
  18                     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>
  19 Lets you control miscellaneous settings that doesn't fit elsewhere.
  20 </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>
  21 Insert expression parentheses
  22 </p><a class="indexterm" name="d0e4907"></a><a class="indexterm" name="d0e4912"></a><p>
  23 It is always good advise to use more parentheses than you think you need. They
  24 may not be needed, but they add clarity and don't cost anything.
  25 </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">
  26 int result = 12 + 4 % 3 * 7 / 8;
  27 </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">
  28 int result = 12 + ((4 % 3 * 7) / 8);
  29 </pre></td></tr></table></div><p></p></li><li><p><a name="misc-insert-uid"></a>
  30 Insert serial version UID
  31 </p><a class="indexterm" name="d0e4932"></a><p>
  32 Common sense dictates to declare an explicit serial version UID in every
  33 serializable class to eliminate the serial version UID as a potential source
  34 of incompatibility (with the additional benefit of a small performance gain).
  35 If this switch is enabled and the class directly dereives from either
  36 <tt class="filename">java.io.Serializable</tt> or <tt class="filename">java.io.Externalizable</tt>,
  37 Jalopy computes and inserts a serial version UID for the class.
  38 </p><p>
  39 For this feature to work, the class that has its serial version UID computed
  40 needs to be available on the classpath.
  41 </p></li><li><p><a name="misc-logging-conditional"></a>
  42 Insert logging conditional
  43 </p><p>
  44 Typically, logging systems have a method that submits a logging message like
  45
  46 </p><table border="0" bgcolor="#E0E0E0" class="shade"><tr><td><pre class="screen">
  47 logger.debug("some message: " + someVar);
  48 </pre></td></tr></table><p>
  49 </p><p>
  50 This is fine, but if the debug level is set such that this message will
  51 <span class="emphasis"><em>NOT</em></span> display, then time is wasted doing the string marshalling.
  52 </p><p>
  53 Thus, the preferred way to do this is
  54
  55 </p><table border="0" bgcolor="#E0E0E0" class="shade"><tr><td><pre class="screen">
  56 if (logger.isDebugEnabled()) {
  57     logger.debug("some message: " + someVar);
  58 }
  59 </pre></td></tr></table><p>
  60
  61 which will only use CPU time if the log message is needed. Enabling this switch
  62 will ensure that every logging call with the debug level set will be enclosed with
  63 the conditional expression.
  64 </p><p>
  65 Use this feature with care! The current implementation only supports the Jakarta
  66 Log4J toolkit and is somewhat weak in that every method call called
  67 <i class="firstterm">debug</i> is treated as a logging call which could be incorrect
  68 in your application. However, it works fine for the <i class="firstterm">l7dlog</i> calls.
  69 </p></li><li><p><a name="misc-trailing-newline"></a>
  70 Insert trailing newline
  71 </p><p>
  72 If enabled, Jalopy inserts an empty line at the end of every file. This may
  73 help to avoid problems with certain text formatters and processors.
  74 </p><p>
  75 Note that Jalopy always inserts at least one empty line after footers, so there
  76 is no real need (but it doesn't hurt) to check the mark in case footer insertion
  77 will be performed (see <a href="footer.html" title="4.3.11.&nbsp;Footer">Section&nbsp;4.3.11, &#8220;Footer&#8221;</a>)
  78 </p></li><li><p><a name="misc-array-brackets"></a>
  79 Array brackets after identifiers
  80 </p><p>
  81 Lets you choose where the brackets of array types should be placed.
  82 </p><p>
  83 By default, Jalopy prints the square brackets right after the array type.
  84 </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">
  85 int[] a;
  86 </pre></td></tr></table></div><p>
  87 But C/C++ programmers may expect them to appear after the identifier.
  88 </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">
  89 int a[];
  90 </pre></td></tr></table></div><p></p></li><li><p>
  91 Force formatting
  92 </p><p>
  93 Jalopy can keep track of which files have been formatted previously.
  94 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
  95 exclude files that have a modification date coincident with the last formatting.
  96 However, you can override this history check to force a format. For example,
  97 you might need to update the copyright notice for the whole code base. Enabling
  98 this switch ensures that all source files are always be formatted. Note that
  99 this switch is only meaningful if the history feature is enabled.
 100 </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>
 101 The history feature offers a way to optimize the speed at which Jalopy processes
 102 of a group of files repeatedly. Using history, Jalopy is able to track file
 103 modifications between successive invocations, and only format those source
 104 files which have actually changed, or which weren't processed previously.
 105 This can save a huge amount of execution time for a project that is formatted
 106 repeatedly over time. There are two methods for keeping history.
 107 </p><div class="itemizedlist"><ul type="disc"><li><p><a name="history-file"></a>
 108 Use history file
 109 </p><a class="indexterm" name="d0e5019"></a><a class="indexterm" name="d0e5024"></a><p>
 110 If you can't get along with a history header comment at the top of each source
 111 file, but would like historical optimization, the file-based approach may work
 112 for you. The history information of previous formatting will be saved in a file
 113 <tt class="filename">history.dat</tt> under the Jalopy settings directory.
 114 </p><p>
 115 Note that this file will grow over time, especially if one manages several big
 116 projects. So the history file could become quite huge. As all history entries
 117 are read into memory at startup, it could eat up quite a bit of memory space.
 118 Therefore a little history viewer is provided which enables you to selectively
 119 remove obsolete entries.
 120 </p><p>
 121 In order to effectively use formatting of a project with several developers it is
 122 nice to be able to only format files which have changed. There are three methods of
 123 working out if a file has changed provided in a drop down. Timestamp will use the
 124 modification time of the file, this does not work very well with source control
 125 and multiple developers. There are two standard checksums available. These
 126 work by taking a checksum of the file and comparing it to the one in the history file.
 127 If this checksum is different, the file is parsed and formatted in memory and a new
 128 checksum calculated. If the new checksum is different than the checksum for the
 129 unformatted file, it is written to disk. This stops files that have just been updated
 130 from source control from having being formatted (and timestamps updated).
 131 </p><p>
 132 Use the <span><b class="guibutton">View...</b></span> button to display the history viewer. You
 133 can selectively remove entries via the popup menu.
 134 </p></li><li><p><a name="history-comment"></a>
 135 Use history comments
 136 </p><a class="indexterm" name="d0e5044"></a><a class="indexterm" name="d0e5049"></a><a class="indexterm" name="d0e5054"></a><p>
 137 Jalopy will insert a small comment in the first line of every source file.
 138 The comment encodes the time a file was last formatted along with the package
 139 name of the file. This method is precise and relatively foolproof but does not work well
 140 with SCM tools.
 141 </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>
 142 For security reasons Jalopy creates a backup copy of the currently
 143 processed file so it can be restored in case a severe error occured during the
 144 formatting process. The original file is stored in the backup directory and normally
 145 deleted after the newly formatted file has been successfully written.
 146 </p><div class="itemizedlist"><ul type="disc"><li><p>
 147 Level
 148 </p><p>
 149 The backup level defines how many numbered backups should be retained (up to 30).
 150 The default is to never hold any backups.
 151 </p></li><li><p>
 152 Directory
 153 </p><p>
 154 Specifies where file backups are stored. You should leave this setting untouched
 155 in order to make your code convention portable across different systems and platforms.
 156 </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>
 157 Jalopy, more precisely the provided Plug-ins, are multi-threaded. On
 158 multi-processor systems the work can be divided onto several processors to
 159 speed up processing.
 160 </p><div class="itemizedlist"><ul type="disc"><li><p>
 161 Number
 162 </p><p>
 163 Specifies the number of processing threads to be used. This setting should be
 164 equal to the number of processors your system has.
 165 </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">
 166             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>