Java Random Notes

Constants in Java...

public class Clazz
{
  private final static String         PATHNAME = "src/test/resources/";    // class constant
  private final        String         FILENAME = "test.dat";               // instance constant
  private              List< String > barNames;                            // instance variable

  private void bar( final String barName )                                 // constant parameter
  {
         int    counter;                                                 // local variable
    final double PI = "3.14";                                             // local constant

    for( final String name : barNames )                                   // local "constant" (within code block)
      ...
  }
}

At its core, the Java virtual machine (JVM) consists of the following components:

• Heap
• Stack
• PermGen and method area
• Just-in-time (JIT) compiler
• Code cache

The heap is where memory is allocated for every new operator you use during the application code development stage.

Local variables which remain within the scope of a method are stored on the stack. As a method or block in a method goes out of scope, those variables are removed. (Note too that once Java objects no longer have live references to them, they are garbage-collected.)

PermGen space stores class and method-level data as well as static variables that are defined by the application. A method area is in PermGen and stores all method, field and constant pool details of the application.

The JIT and the code cache go hand-in-hand. The JVM at its core interprets and converts the Java byte code into assembly code at run-time. Interpreting is a relatively slow process because the code is converted from byte code to machine code on the fly every time a portion of your application code is executed. This is where the JIT compiler swings into action:

The JIT compiler analyzes the application code at run-time to understand which methods can be categorized as "hot" methods. Hot means code fragments that are accessed more frequently. Conceptually, the JIT compiler has a counter for each method executed in order to understand the frequency of usage. When the counter's value reaches a defined threshold, the method becomes eligible to be compiled by the JIT compiler to assembly which is then stored in the code cache. From then on, whenever the JIT compiler comes across a call to such a pre-compiled and cached method, it will no longer try to reinterpret it, but will use the already compiled assembly code. This gives the application an obvious performance boost.

I do this from .profile. I usually maintain a private JDK locally for use by IntelliJ (or Eclipse back in the day) so that, when I'm developing in Java, there are no surprises.

# set up JAVA_HOME...
if [ -e "$HOME/dev/jdk-alternative" ]; then
  # ...to my private copy if present:
  export JAVA_HOME="$HOME/dev/jdk-alternative/"
else
  # ...or to the one on my Linux Mint/Ubuntu system:
  export JAVA_HOME="/usr/lib/jvm/default-java/"
fi

...where XXX is the process id (pid), this is Java's (the JVM's) fatal-error log, created with information and the state obtained at the moment of the fatal error.

The JVM option, -XX:ErrorFile=path may be used to specify where this file is created. Otherwise, it's created a) in the working directory of the process assuming adequate space, filesystem permissions and no other issues, or it's created on /tmp. The JVM always attempts to create this file (and, if it fails, worse stuff than just a crashed Java application is afoot on the system).

It's always safe to remove this file when you find it since, if you see it, it's for a crash that's already happened, it was per-pid, the JVM no longer expects to use it and will just create another (even if the same pid is used) when a fatal error occurs.

A collection of utility methods isn't OOP (with a capital OOP). These methods should be static since their behaviour is not dependent on any specific instance of attributes.

A static variable in a class becomes a single instance for all instantiations of objects of that type. If changed by one, it's changed for all objects. static final will ensure its inability to be modified.

Declare immutable constants as static final. This guards against inadvertant modification and permits the compiler to perform optimizations in the use of those values.

Use camel-back, lower-case initial in the names of methods and non-constant variables.

A char cannot be safely converted to byte.

Never use exceptions for flow-control.

..are formal names for getters and setters.

int to String

	int      x = 99;
	String   X = Integer.toString( x );
	// or
	String   X = "" + x;

Use this to close streams, file handles, database connections, etc. StreamUtils.close() is your short-hand friend for the first case.

	Properties      properties = new Properties();
	FileInputStream is         = null;

	try
	{
	  is = new FileInputStream( path );
	  properties.load( is );
	}
	catch( FileNotFoundException e )
	{
	  System.out.println( e.getMessage() );
	}
	catch( IOException e )
	{
	  System.out.println( e.getMessage() );
	}
	finally
	{
	  StreamUtils.close( is );
	}

Research this class for transforming an input stream into an output stream and vice-versa.

In Java I/O, a file or other device may be opened on a stream and somewhere in the layer cake that wraps the device may be a reader. A reader augments a stream in that it deals with characters (UTF-8, etc.) rather than bytes.

This is not an exhaustive treatment of concurrency solutions in Java. It is a simple treatment, from a C programmer's mentality, of the Java keyword, synchronized. Java uses this keyword in two ways.

Synchronized blocks

The synchronized keyword is used to synchronize a block of executable statements by referring to an object. This object becomes like a mutex in procedural programming languages: executing all other blocks with reference to object is serialized:

	Object object = new Object();

	synchronized( object )
	{
	  do something with object;
	}

How it works

On its face, object is not any kind of mutex, condition variable, reader-writer lock, barrier or other synchronization primitive that you would expect to declare in a procedural language to manage your protected data in parallel. But in fact, every Java object contains a lock within itself. This lock is formally referred to as a monitor. When the compiler sees synchronized in this situation, it generates code to use the object's monitor.

Synchronized methods

The synchronized keyword is also used to synchronize goings on in a method. This is also like controlling execution of the method based on a mutex, but the object is implied this rather than explicit.

	synchronized void makeSomeoneHappy()
	{
	  do something to make someone happy with several objects;
	}

All synchronized methods share the same mutex (this, as noted). The above is directly equivalent to:

	void makeSomeoneHappy()
	{
	  synchronized( this )
	  {
	    do something to make someone happy with several objects;
	  }
	}

Watch out!

A private member variable in a class isn't safe unless all methods touching it are explicitly synchronized. A public member variable would practically never be safe. In the following class, x is safe, but y is not even though their manipulating methods are synchronized.

	public class TwoCounters
	{
	  private int x = 0;
	  public int  y = 0;

	  public synchronized getX() { return this.x; }
	  public synchronized incX() { this.x++;      }
	  public synchronized zeroX(){ this.x = 0;    }

	  public synchronized getY() { return this.y; }
	  public synchronized incY() { this.y++;      }
	  public synchronized zeroY(){ this.y = 0;    }
	}

This is because code outside this class can freely access y whereas an attempt to access x would be rebuffed by the compiler:

	TwoCounters counter = new TwoCounters();

	counter.y = 99;        PASSES COMPILER, BUT A BAD IDEA!
	counter.x = 99;        COMPILATION ERROR!

The distinction between the two methods of synchronization just contrasted is that in the second case, no actual, explicit object is needed in writing the code to perform serialization. There is no need to create object. Instead, the implied object, this, is used.

(Yup, this is absolutely the first time in over a decade of writing HTML that I have used the <blink> tag: very annoying, isn't it?)

Deadlocking

Between correctly synchronized methods in diverse classes deadlocks can easily occur, in particular, the ABBA. The following is the scenario.

1. Thread A enters a synchronized method for class Foo. It holds the monitor for Foo's this. Let's say that thread A blocks momentarily on some I/O operation.
2. Thread B enters a synchronized method for class Bar. It holds the monitor for Bar's this. Thread B also knows about the same instance of Foo as thread A and attempts to enter one of Foo's synchronized methods. Foo's monitor is contested because thread A already has it.
3. Thread A wakes up from its I/O operation and, having a reference to the instance of Bar that thread B already has locked, decides to attempt to enter one of Bar's synchronized methods.
4. Thread A is blocked on a monitor held by thread B and thread B is blocked on a monitor held by thread A.

This sort of nightmare is best prevented by careful design. The temptation by bad engineers in a procedural language might be to test whether a lock is going to be contested before attempting to use it and, indeed, it is sometimes impossible to do otherwise. However, all efforts to design logic to avoid doing this should be made. Moreover, as noted next, it was not possible prior to Java 1.5 to perform a try-lock.

More traditional locking in Java

Starting (only) in Java 1.5, a new interface, Lock, is provided to mimic not only mutexes in use in other, especially procedural languages, but also try-locking mutexes, condition variables and reader-writer locks.

Without giving an implementation here (because that is how one chooses to implement a mutex versus a condition variable versus a reader-writer or other kind of lock), this example shows how it is used:

	Lock l = new ...();

	l.lock();

	try
	{
	  do something with resources controlled by lock l;
	}
	finally
	{
	  l.unlock();
	}

This usage is unsurprising and recognizable to any C programmer. The reason for this to exist (finally) in Java is that it gives greater flexibility (if also imposing the inelegant coding duty of maintaining the lock just as in C). Using synchronized does not give you the finer control to do something else in the case the object is contested: you are blocked on permanently on the object (explicit object or implicit this) until the thread that has it locked yields it. Hence the utility of this new interface.

Much is configurable in Java and:

	String property = System.getProperty( property-name);

...is how a property is got. There are three ways they are set.

First, Sun sets them, like java.io.tmpdir, predefined, in its JRE. Other JREs do too and, from platform to platform, there is sometimes the tiniest bit of non-conformance.

Second, you can set them yourself using the command line:

	# java  -Dhow.i.feel=blue  MyClass

Last, you can set them programmatically:

	String libraries = System.getProperty( "java.library.path" );

	if( libraries != null && libraries.length() != 0 )
	  libraries += ":" + "/home/russ/dev/libs";
	else
	  libraries = "/home/russ/dev/libs";

	System.setProperty( "java.library.path", libraries );

A temporary file is created in java.io.tmpdir:

	File f = File.createTempFile( "fun", ".poo" );

	System.out.println( "Just created file "
	                    + f.getName()
	                    + " in directory "
	                    + System.getProperty( "java.io.tmpdir" )
	                   );

The ternary operator in Java is problematic, having trouble with mixed, ambiguous or unclear typing in places where humans do not.

In the example, a compile-time error is generated. In order to force understanding on the compiler, use parentheses as shown in the subsequent line. This forces evaluation of the expression before settling on what type is its result.

Type mismatch: cannot convert from String to boolean.

	Double x = 9.0;

	System.out.println( "This is a " + ( x == 9.9 ) ? "test" : "cat" + " of the Emergency Broadcast System" );

	/* fixed: */
	System.out.println( "This is a " + ( ( x == 9.9 ) ? "test" : "cat" ) + " of the Emergency Broadcast System" );

To run from the command line a JUnit test you've created, you need a main() method to call it. Create your JUnit test class as normal, here, FunTest, create another class with a public static void main( String[] args ) inside that calls it thus:

    import junit.textui.TestRunner;

    public class RunnableFunTest
    {
        public static void main( String[] args )
        {
            TestRunner.run( FunTest.class );
        }
    }

Obviously, when you run this from the command line, you'll also have to make allowances for the JUnit JAR (library) to be present.

• Observe whether system up-time increases the likelihood of running out of memory.
• Use jmap to take a memory dump. It doesn't count objects that aren't referred to, which will be the object of garbage collection soon anyway. This means it has a much smaller effect on the production JVM.
• Think about what your service is doing and how it can be abused by clients. For example, can a client do something that will cause memory to leak, perhaps by making requests that allocate memory or connections repeatedly that are not closed for some reason? This may betray a mistake in your design.
• Enable the garbage-collection log via JVM argument, -XX:+PrintGC.
• Use jmap multiple times at calculated intervals to ascertain the memory-accumulating pattern.

  $ jmap -histo:live process-id
  

• Keep a seconds-based progress log early on in order to understand your service depending on what the service does. Do this using the TRACE level logger. For example, each second, print out
  • number of requests coming into the service
  • number of requests to fire all the way through
  • number of successful requests
  • number of failed requests
  • number of requests timing out
  The objective, of course, is to compare this to the jmap histogram. Anything weird happening is put into better context.

I used to code in C and assembly on a multithreaded, multiprocessor operating system (NetWare). I knew all the ins and outs. Java, however, is not C and has different ways of doing things. Here are the details on the Java synchronized keyword:

• Synchronized code: This locks code down a little like a barrier in C. (Well, okay, not much like that, but it's sort of the same idea.)

  public synchronized method()
  {
    ...
  }
  
  

• Synchronize code on a variable: actually, this is what's really happening even in the case above because the variable there is implicit. If execution encounters code attempting to synchronize on the same object, then that object becomes, like a mutext, contended.
• Another, more intelligent way to support thread-safe execution in Java includes, just as in other languages including C, to eliminate shared data. If threads don't share objects, then it doesn't matter when threads run or what they do to their data.

When you see a stack trace with...

    java.lang.UnsupportedClassVersionError: SomeClass : Unsupported major.minor version 51.0 (unable to load class SomeClass)
    .
    .
    .

...it probably means that you compiled your application with a Java compiler of a more recent version than the JVM you're trying to run it on.

Equivalence must define a relation that's reflexive, symmetric, transitive and consistent. If null, what's being compared must return false. Apache Commons has some great helps for this.

import org.apache.commons.lang3.builder.EqualsBuilder;
import org.apache.commons.lang3.builder.HashCodeBuilder;

public class Poop
{
    private String name;
    private int    age;

    public boolean equals( Object o )
    {
        if( o == null )
            return false;
        if( o == this )
            return true;
        if( !( o instanceof Poop ) )
            return false;

        Poop poop = ( Poop ) o;

        return new EqualsBuilder()
                    .append( name, poop.name )
                    .append( age, poop.age )
                    .isEquals();
    }

    public int hashCode()
    {
        return new HashCodeBuilder( 17, 31 )    // two randomly chosen prime numbers
                        .append( name )
                        .append( age )
                        .toHashCode();
    }
}

Not that I feel the need to do this. OpenJDK/JRE usually works fine and so does the Sun JDK/JRE. At work, they were in a "let'd get rid of Oracle" mood and while that's really only a database issue, it was proposed that the baby get tossed out too. No matter. Here's how I did it; I'm running Mint (Ubuntu) these days.

Please note that Oracle/Sun typically installs on the host at /opt/java, e.g.: /opt/java/jdk1.7.0_51. It is not seen via dpkg --list nor removed via apt-get purge/remove.

I'm dumbing this down a bit to reveal all the details that would otherwise have to be guessed at.

If it's really a JDK (and not merely a JRE) and you've done everything right, IntelliJ should start without the "missing tools.jar / please use a proper JDK message".

1. Install openjdk 7, the one you want.

   ~ $ sudo bash
   ~ # apt-get update
   ~ # apt-get install openjdk-7-jdk
   

2. Fix up links in /usr/lib/jvm:

   /usr/lib/jvm # ll
   total 56
   drwxr-xr-x   4 root root  4096 Jun 25 12:52 .
   drwxr-xr-x 203 root root 36864 Jun 25 12:52 ..
   lrwxrwxrwx   1 root root    18 Mar 13  2012 java-1.5.0-gcj -> java-1.5.0-gcj-4.6
   drwxr-xr-x   6 root root  4096 Feb  7 14:03 java-1.5.0-gcj-4.6
   lrwxrwxrwx   1 root root    20 Apr 25 12:31 java-1.7.0-openjdk-amd64 -> java-7-openjdk-amd64
   -rw-r--r--   1 root root  2439 Apr 25 12:31 .java-1.7.0-openjdk-amd64.jinfo
   drwxr-xr-x   5 root root  4096 Jun 25 10:56 java-7-openjdk-amd64
   lrwxrwxrwx   1 root root    12 Mar 13  2012 java-gcj -> java-gcj-4.6
   lrwxrwxrwx   1 root root    18 Apr 16  2012 java-gcj-4.6 -> java-1.5.0-gcj-4.6
   -rw-r--r--   1 root root   946 Apr 16  2012 .java-gcj-4.6.jinfo
   

3. I added this link.

   lrwxrwxrwx   1 root root    26 Jun 25 13:06 java-7 -> ./java-1.7.0-openjdk-amd64
   

4. Fix up /etc/alternatives.

   /etc/alternatives # ll java
   lrwxrwxrwx 1 root root 30 Feb  7 14:05 java -> /opt/java/jdk1.7.0_51/bin/java
   

   which I changed to:

   /etc/alternatives # ll java*
   lrwxrwxrwx 1 root root 30 Feb  7 14:05 java.old -> /opt/java/jdk1.7.0_51/bin/java
   lrwxrwxrwx 1 root root 28 Jun 25 13:08 java -> /usr/lib/jvm/java-7/bin/java
   

   I can remove java.old once everything is working.

5. Fix up your .profile, something like:

   export JAVA7_HOME=/usr/lib/jvm/java-7-openjdk-amd647
   export  JAVA_HOME=${JAVA7_HOME}
   export   IDEA_JDK=${JAVA7_HOME}
   export    M2_HOME=/home/russ/dev/apache-maven-3.1.1
   export         M2=${M2_HOME}/bin
   export MAVEN_OPTS="-Xms2048m -Xmx2048m -XX:PermSize=256m -XX:MaxPermSize=512"
   
   PATH=/home/russ/bin:${JAVA_HOME}/bin:${PATH}
   PATH=${PATH}:${M2}
   

   so that your path appears thus:

   ~ $ echo $PATH
   /home/russ/bin:/usr/lib/jvm/java-7/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:\
       /sbin:/bin:/home/russ/dev/apache-maven-3.1.1/bin
   ~ $ which java
   /usr/lib/jvm/java-7/bin/java
   ~ $ java -version
   java version "1.7.0_55"
   OpenJDK Runtime Environment (IcedTea 2.4.7) (7u55-2.4.7-1ubuntu1~0.12.04.2)
   OpenJDK 64-Bit Server VM (build 24.51-b03, mixed mode)
   

The first things to remember are that Java 5 introduced...

1. Annotations, including @Override.
2. Interfaces, which had not existed before (everyone use abstract).

In Java 5, @Override was introduced for use in overriding a method from a superclass (including abstract classes). It was not offered for use on methods implementing a method from an interface.

In Java 7, @Override is tolerated for methods of a class that implement methods listed in an interface. However, it is not necessary. This is why you don't get errors for either method below:

public interface Foo
{
    public void fooit();
    public void barit();
}

public class Bar implements Foo
{
    @Override
    public void fooit() { }

    public void barit() { }
}

Nevertheless, when compiling with Java 6, you do get an error for the implementation of fooit().

I personally think it makes more sense not to use @Override when implementing an interface's contractual methods, but it's only a problem when you maintain code compiled sometimes by JDK 5/6 and sometimes by JDK 7/8.

The Java map consists of HashMap, LinkedHashMap, TreeMap and Hashtable.

HashMap - makes no guarantee as to order, allows one null key and null values. Traversed using iteratory, entry set. (Inherits AbstractMap.)

LinkedHashMap - preserves the original insertion order, but is otherwise identical to HashMap.

TreeMap - uses natural or comparator-based ordering to maintain contents in-order. Null keys only allowed if comparator used and doesn't thrown an exception.

Hashtable - makes no guarantee as to order, disallows null keys and values, is synchronized and therefore expensive if you don't need that. Traversed using enumerator and iterator. (Inherits Dictionary.)

You try to create a file. Where is it? Original, Windows code:

File child = new File(".././Java.txt");

• getPath() —likely relative to current working subdirectory.
..\.\Java.txt
• getAbsolutePath() —fully qualified path, but in relationship to the current working subdirectory.
C:\Users\WINDOWS 8\workspace\Demo\..\.\Java.txt
• getCanonicalPath() —full path from the filesystem's point of view.
C:\Users\WINDOWS 8\workspace\Java.txt

byte[] aByte = new String( ".976" ).getBytes();
String propertyValue = new String( aByte );

...otherwise, aByte.toString() yields gobble-dee-gook.

... exist in checked and unchecked varieties. The original idea:

Unchecked exceptions represent defects in the application code, perhaps a null pointer, an invalid argument passed to a non-private method. These represent conditions that, generally speaking, reflect errors in logic and cannot be reasonably recovered from at runtime.

At least that was the theory in the 1990s.

Checked exceptions are invalid conditions in area outside immediate control of application code including invalid user input, database problems, network outages, absent files, etc.

They are subclasses of Exception.

Methods are obliged to establish a policy for all checked exceptions thrown by its implementation (either by passing the problem further up the stack or throwing again to be handled elsewhere).

If a client can reasonably be expected to recover from an exception, make it a checked one. If unreasonable, make it unchecked. Avoid unnecessary use of checked exceptions which place a burden on the programmer.

1. Any exception that can be thrown by a method is part of the method's public programming interface.
2. Methods calling such a method must know about the exceptions that the latter can throw and decide what to do about them.
3. Runtime exceptions represent (only) problems that are the result of a programming solutions from which the calling method cannot be reasonably expected to recover or handle in any graceful or useful way. This would include dividing by zero, null-pointer references and indexing exceptions (attempting to access a list or array with an index outside the existing bounds of the data). Illegal arguments are also reasons to throw RuntimeException. Forcing code to check such exceptions reduces the clarity of the code.
4. Moral of the story: If code cannot reasonably or usefully recover from an exception, then leave it as an unchecked exception. Otherwise, make it a checked exception.

                   ┌───────────┐
                   │ Throwable │
                   └───────────┘
                    /         \
                   /           \
          ┌───────┐          ┌───────────┐
          │ Error │          │ Exception │
          └───────┘          └───────────┘
           /  |  \           / |        \
          \_______/       \______/       \
                                      ┌──────────────────┐
          unchecked        checked    │ RuntimeException │
                                      └──────────────────┘
                                        /   |    |      \
                                       \_________________/

                                            unchecked

This is API theory: the right/best way to do things.

Returning null

This means the intent of the code is not explicit without looking at the JavaDocs, and so the worst option on our list.

Returning an Optional< T >

This makes the intent explicit compared to returning null. Of course, this requires Java 8.

Return a Guava's Optional< T >

For those of us who are not fortunate enough to have Java 8.

Returning one's own Optional< T >

If you don't use Guava and prefer to embed your own copy of the class instead of relying on an external library.

Returning a Try

Cook up something like Scala's Try, which wraps either (hence its old name, "Either") the returned bean or an exception. In this case, however, the exception is not thrown but used like any other object, hence there will be no performance problem.

Conclusion: when designing an API, one should really keep using exceptions for exceptional situations only.

A better piece of advice (not mine, but a quote I read somewhere):

"When designing an API, I use the "get vs. find rule." The API's user needs to know how to handle the absence of a result. A get is expected to always return a result while a find is not. And so when coding getX() it returns the result or throws an exception—such as llegalStateException—if there is not one. Where as, when coding findX() it returns a result if available or a null, or an empty collection, if there is not one."

1. Throwable and Error classes should not be caught

Throwable is the superclass of all errors and exceptions in Java. Error is the superclass of all errors which are not meant to be caught by applications. Thus, catching Throwable would essentially mean that Errors such as system exceptions (e.g., OutOfMemoryError, StackOverFlowError or InternalError) would also get caught. The recommended approach is that an application should not try to recover from errors such as these. Therefore, Throwable and Error classes should not be caught. Only Exception and its subclasses should be caught.

Data errors such as encoding issues etc which are not known at programming time should be caught using this technique. However, catching Throwable such as InternalError or OutofMemoryError would not be of any help and should never be thrown.

Avoid writing code consisting of catching Throwable as general practice.

2. Throwable.printStackTrace(...) should never be called

One should avoid invoking printStackTrace() method on Throwable/Exception classes and instead use a logging framework.

3. Generic exceptions Error, RuntimeException, Throwable and Exception should never be thrown

The primary reason to avoid throwing generic Exceptions, Throwable and Error is that doing so prevents classes from catching the intended exceptions. A caller cannot examine the exception to determine why it was thrown and consequently cannot attempt recovery.

Catching RuntimeException is considered a bad practice. Throwing generic Exceptions/Throwable leads the developer to catch the exception at a later stage which usually leads to worse practices.

Do not throw a generic exception like RuntimeException. Do, however, throw a custom-rolled exception that inherits from RuntimeException.

4. Exception handlers should preserve the original exception

5. System.out or System.err should not be used to log exceptions

The primary reason one should avoid using System.out or System.err to log exceptions is that one might simply loose the important error message.

Checked exceptions!

One man's opinion...

It is an utterly failed experiment because it is designed around the totally flawed assumption that the service/library throwing the exception should decide which ones should be checked and which ones should not. In reality, only the caller knows which ones should be caught (usually none), and which ones should not.

6. Generally, whenever a library-method is called that throws a checked exception, just do:

try
{
  libraryObject.method();
}
catch( Exception e )
{
  throw new MyAppRuntimeException( e );
}

...to prevent this checked-exception idiocy from propagating like a virus and infecting the whole application.

Throwing java.lang.Exception is bad practice...

Exception thrown explicitly by your code becomes impossible to discriminate from among other (unexpected) exceptions in a catch clause.

Better by far to pick a more specific exception, including manufacturing a proprietary one if there's nothing obviously suitable.

...to think about and perhaps solve. Some are unavoidable—foisted upon one by someone else, some are code stench.

1. Checking a value returned to me from code I own (null-pointer check stench)?
2. Checking a value returned to me from code I do not own?
3. Checking a parameter passed to me by code I own (control couple stench)?
4. Checking a parameter passed to me by code I do not own?
5. Checking my own state or attributes?
6. Checking a value I set previously in this method?
7. Checking the type of an exception thrown by code I own?
8. Checking the type of an exception thrown by code I do not own?

This code doesn't close streams although it's trying. It could throw an exception when one fails to close. If attempting to close fis fails, the code throws an exception and prints out a warning, but nothing is done to attempt to close fos.

FileInputStream  fis = null;
FileOutputStream fos = null;

try
{
  fis = new FileInputStream( "stuff-to-read.txt" );
  fos = new FileOutputStream( "stuff-put-out.txt" );
  ...
}
finally
{
  try
  {
    if( fis != null )
      fis.close();
    if( fos != null )
      fos.close();
  }
  catch( IOException e )
  {
    System.out.println( "Failed to close streams" );
  }
}

This code will do the trick, but it's a bit unsightly. It takes up a lot of space and obfuscates a simple thing.

InputStream  fis = null;
OutputStream fos = null;

try
{
  fis = new FileInputStream( "stuff-to-read.txt" );
  fos = new FileOutputStream( "stuff-put-out.txt" );
  ...
}
finally
{
  try
  {
    if( fis != null )
      fis.close();
  }
  catch( IOException e )
  {
    ;
  }
  try
  {
    if( fos != null )
      fos.close();
  }
  catch( IOException e )
  {
    ;
  }
}

Beware (duh!) that if you have a duplicate class, EarlyExitException, in your code and are building using a JAR that also has that symbol, uses and throws it, your code will not be catching it just because you happen also to have EarlyExitException. They are different and you get errors like

unreported exception EarlyExitException; must be caught or declared to be thrown

because EarlyExitException is not EarlyExitException.

This happens when you've got code in your JAR, WAR or NAR compiled with a higher version of Java (in my case 8) for a higher version of Java (in my case, 8 though I wasn't specifying it by using this plug-in).

	<plugin>
		<groupId>org.apache.maven.plugins</groupId>
		<artifactId>maven-compiler-plugin</artifactId>
		<configuration>
			<source>1.7</source>
			<target>1.7</target>
		</configuration>
	</plugin>

The solution is to build everything with 1.7 (or whatever). Use Maven to clean out what's there before recompiling and packaging with this plug-on configuration in place.

public class SerializableClass implements Serializable
{
  private static final    long   serialVersionUID = 456778567857L;
  public                  String firstField       = "First Field";
  public transient static String secondField      = "Second Field";
  public transient final  String thirdField;      // unintialized
  public transient final  String fourthField      = "Fourth Field";
  private int                    privateField     = 99;

Notes

1. serialVersionUID is explicitly defined to prevent InvalidClassException during deserialization. As the default serialVersionUID computation is highly sensitive to class details that may vary depending on compiler implementations and can produce different results in different environments, beware.
2. firstField will be serialized, and the default value can be overridden in subsequent classes that are serializing SerializableClass.java.
3. secondField, thirdField and fourthField, being either transient static or transient final, will never be serialized. The values these will have will be restored at deserialization from whatever their values are in SerializableClass at the time it happens.
4. privateField is private. It will be serialized, but can be read only through reflection.

These are the causes of the JVM garbage collection firing according to frequency in an average application.

An immutable class is simply one whose objects, once they've been instantiated, are unmodifiable, i.e.: cannot be changed. These include String, most implementations of date and time classes and wrapper classes (c'est-à-dire Boolean, Short, Long, Double, Float. There are other examples such as File. Classes following the Singleton pattern are typically immutable. Enumerations are typically immutable (unless they've been badly coded).

Benefits of immutable classes:

• as noted, the object never changes
• their methods are thread-safe

Steps to creating an immutable class:

1. Make all instance variables/fields private for no direct access.
2. Initialize only using constructors.
3. Make all instance variables/field final so they can't be changed without failing compilation.
4. If providing for cloning, make it a deep-clone, that is, one that does not copy object references including
   • the object itsef
   • any object internal to the object
5. Provide no setter methods.
6. Provide no getter method that fails to deep-clone the object it returns.
7. Define the class as final in order that it not be extendable.

public void funWithRegularExpressions( final String patient_local_id )
{
  // 'patient_local_id' contains "Mercy_Hospital:665892"
  String facilityName, separator, facilityId;
  Pattern pattern;
  Matcher matcher;

  pattern      = Pattern.compile( "^([\\w\\s]+)\\W.+$" );
  matcher      = pattern.matcher( patient_local_id );
  facilityName = ( matcher.find() ) ? matcher.group( 1 ) : patient_local_id;

  pattern      = Pattern.compile( "^[\\w\\s]+(\\W).+$" );
  matcher      = pattern.matcher( patient_local_id );
  separator    = ( matcher.find() ) ? matcher.group( 1 ) : patient_local_id;

  pattern      = Pattern.compile( "^[\\w\\s]+\\W(.+)$" );
  matcher      = pattern.matcher( patient_local_id );
  facilityId   = ( matcher.find() ) ? matcher.group( 1 ) : patient_local_id;

  System.out.println( "Facility name: " + facilityName );
  System.out.println( "    Separator: " + separator );
  System.out.println( "  Facility id: " + facilityId );
}

Output:

Facility name: Mercy_Hospital
    Separator: :
  Facility id: 665892

In a twist right out of Paul Simon's, When Numbers Get Serious (read second verse), I just encountered this weirdness today. I guess I don't do stuff like this very often, but I was surprised to see it and I struggled to find wording in Google to find its explanation:

1. int x = 1;
2. System.out.println( "x = " + x );
3. System.out.println( "x+1 = " + x+1 );

Output is:

x = 1
x+1 = 11

Freaky. I was doing this in some code I wrote.

So, what's going on? On line 3, the + operator is string concatenation rather than arithmetic addition. Operator precedence assures that x's value is converted to a string, concatenated "x+1 = ", then the value 1 is converted to a string and concatenated to the previous string.

Ordinarily, one consumes a .so on the path indicated by LD_LIBRARY_PATH. However, this isn't necessarily set to anything especially when running or debugging in Eclipse, IntelliJ IDEA, etc.

Here's something I tried with success for consuming libsigar-amd64-linux.so:

1. Copy the shared object to project-foldersrc/main/resources.
2. Edit run/debug configurations and add an environment variable:

   LD_LIBRARY_PATH=/home/russ/dev/cassandra/target/classes
   

   This works because, when built, the target subdirectory contains a classes subdirectory to where, in addition to compiled Java class files, anything put into the src/main/resources subdirectory gets copied.

This solution is a bit volatile, however, in that you must maintain this configuration when you run. Run/Debug Configurations in IntelliJ are notoriously volatile. Also, this does nothing for the final Java product JAR and you'll have to copy the shared object to wherever LD_LIBRARY_PATH points before launching your Java application.

I've dealt with this before, but in specific environments and always tentatively. Surely there's something better and more correct to say.

Building at home, I get:

russ@gondolin ~/sandboxes/cassandra-ps-index.clustering_feature.dev/code/cassandra-ps-index $ mvn package
.
.
.
[ERROR] Failed to execute goal org.apache.maven.plugins:maven-compiler-plugin:3.2:compile (default-compile) on project cassandra-ss-index-plugin: Compilation failure
[ERROR] No compiler is provided in this environment. Perhaps you are running on a JRE rather than a JDK?
[ERROR] -> [Help 1]

This is because I have a JRE instead of a JDK, which is what happens by default on a new Linux installation, which is what I have (Linux Mint 18.2 Sonya) since my box sort of exploded a few weeks back. This will fix it, although the alternatives thing never reveals to my satisfaction that I've fixed it:

russ@gondolin ~ $ sudo update-alternatives --config java
There is only one alternative in link group java (providing /usr/bin/java): /usr/lib/jvm/java-8-openjdk-amd64/jre/bin/java
Nothing to configure.
russ@gondolin ~ $ sudo apt-get install openjdk-8-jdk
russ@gondolin ~ $ sudo update-alternatives --config java
There is only one alternative in link group java (providing /usr/bin/java): /usr/lib/jvm/java-8-openjdk-amd64/jre/bin/java
Nothing to configure.

Yeah, looks the same to me. The only way I could tell that things were going to work was:

russ@gondolin ~ $ cd /usr/lib/jvm/java-8-openjdk-amd64/
russ@gondolin /usr/lib/jvm/java-8-openjdk-amd64 $ ll
total 28
drwxr-xr-x 7 root root 4096 Nov 14 08:34 .
drwxr-xr-x 3 root root 4096 Nov  8 06:28 ..
lrwxrwxrwx 1 root root   22 Oct 27 16:51 ASSEMBLY_EXCEPTION -> jre/ASSEMBLY_EXCEPTION
drwxr-xr-x 2 root root 4096 Nov 14 08:34 bin
lrwxrwxrwx 1 root root   41 Jul 27 20:31 docs -> ../../../share/doc/openjdk-8-jre-headless
drwxr-xr-x 3 root root 4096 Nov 14 08:34 include
drwxr-xr-x 5 root root 4096 Nov  8 06:28 jre  # not comforting...
drwxr-xr-x 3 root root 4096 Nov 14 08:34 lib
drwxr-xr-x 4 root root 4096 Oct 25 19:41 man
lrwxrwxrwx 1 root root   22 Oct 27 16:51 THIRD_PARTY_README -> jre/THIRD_PARTY_README
russ@gondolin /usr/lib/jvm/java-8-openjdk-amd64 $ find . -name '*tools*'
./lib/tools.jar                               # ah, now we know...
russ@gondolin ~/sandboxes/cassandra-ps-index.clustering_feature.dev/code/cassandra-ps-index $ mvn package
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 3.778 s
[INFO] Finished at: 2017-11-14T08:44:19-07:00
[INFO] Final Memory: 43M/357M
[INFO] ------------------------------------------------------------------------

1. Always provide a benefit, though this might be slim, like funneling everything through a common point.
2. Following the naming convention of ending the class name by -Exception.
3. Furnish JavaDoc that explains it all (see below).
4. Furnish a constructor that includes the exception's cause.

   /**
    * This exception wraps all checked exceptions and enriches them
    * with a custom error code. You can use this code to retrieve
    * localized error messages and to link to our online documentation.
    */
   public class MyBusinessException extends Exception
   {
     public void wrapException( String input ) throws MyBusinessException
     {
       try
       {
         // do something
       }
       catch( NumberFormatException e )
       {
         throw new MyBusinessException( "A message that describes the error.",
                               e,
                               ErrorCode.INVALID_PORT_CONFIGURATION );
       }
     }
   }
   
   

The thread pool contained inside the ThreadPoolExecutor can contain any number of threads. The number of threads in the pool is determined by variables establish at construction:

• corePoolSize and maxPoolSize. If fewer than corePoolSize threads are created in the the thread pool when a task is delegated to the pool, then a new thread is created, even if idle threads exist in the pool.
• If the internal queue of tasks is full, and corePoolSize threads or more are running, but fewer than maxPoolSize threads are running, then a new thread is created to execute the task.
• Once the number of threads reaches maxPoolSize, and all threads are busy when a new task is submitted, if a handler is registered, then that task is rejected and, the handler takes over. See RejectedExecutionHandler.
• For RejectedExecutionHandler, this can be a very bad idea because it's prone to dead-lock since all the threads in the pool may have died before what you put into the queue is visible. This can be mitigated using a keep-alive delay.

This just bit me (after years writing in Java). It took me some serious head-scratching and Googling to figure it out. The secret is recounted in verbiage only if you understand "Returns a fixed-size list backed by the specified array." That doesn't really jump out at me, but there it is.

List< String > list1 = Arrays.asList( "this", "that", "and", "the", "other" );
List< String > list2 = new ArrayList();
list2.add( "something else" );
list1.addAll( list2 );
-- boom! --

It turns out that Arrays.asList() returns a fixed-size list backed by an array and it's an "unknown UnsupportedOperationException" to attempt to modify its size (maybe other write operations; I didn't try too hard). On the other hand, this works:

List< String > initialList = Arrays.asList( "this", "that", "and", "the", "other" );
List< String > list1 = new ArrayList();
list1.addAll( initial );
List< String > list2 = new ArrayList();
list2.add( "something else" );
list1.addAll( list2 );
-- no boom. --

It is very difficult to troubleshoot JNI class loader issues. The only way to determine if it's a class loader issue is to eliminate all other UnsatisfiedLinkError cases first. If the code looks correct and is loading the correct version of the native library without errors, including the correct bitness package for the JRE, but is failing when creating the library context, then the only remaining explanation is class loader issues. At that point, the environment must be looked at to see where the offending .jar is loaded from. If this is a web application, and the JAR is loaded from a child class loader (i.e., from the web application's WEB-INF/lib directory), then that could point the way. In Java web-application environments, you have to load the native library and classes from a higher-level parent class loader, not from the individual web-application child class loaders.

...from the likes of IntelliJ IDEA or Eclipse.

OpenJDK: $ java    -agentlib:jdwp=transport=dt_socket,address=8000,server=y,suspend=n
Oracle:  $ java -Xdebug -Xrunjdwp:transport=dt_socket,address=8000,server=y,suspend=y

Once the process comes up, you can adjust settings in Edit run configurations... for the port number, which you can choose (here 8000, but it can be anything).

This easily comes up as soon as logging is pushed down from one method (conveniently) into submethods since logging reports line numbers, but a submethod can't give an accurate location.

Of course, there are other problems this solution doesn't solve—like the fact that, if you've set to number lines in log4j.xml (e.g.: see :%L and comment below),

log4j.xml:

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE log4j:configuration SYSTEM "log4j.dtd">
<log4j:configuration debug="false">

  <appender name="console" class="org.apache.log4j.ConsoleAppender">
    <layout class="org.apache.log4j.EnhancedPatternLayout">
      <!-- Produces: 2019-08-02 07:44:28 TRACE c.i.s.MyMethod:248 - (whatever message...) -->
      <param name="ConversionPattern" value="%d{yyyy-MM-dd HH:mm:ss} %-5p %c{1.}:%L - %m%n" />
    </layout>
  </appender>

  <root>
    <level value="TRACE" />
    <appender-ref ref="console" />
  </root>

</log4j:configuration>

...then there will be the wrong line number reported (at very least, confusingly) no matter what your new message says when it's fixed using this solution.

/* Do this to get the current line number to pass
 * down so logging submethod has it right.
 */
logTrace( Thread.currentThread().getStackTrace()[ 1 ].getLineNumber(), ... )

This has got to be somewhat expensive too, but it does avoid the instantiation of a new exception (to get Exception.printStackTrace(), etc.).

Here's how to do thread-local store in Java. Integer, below, could be anything (including an instance of a very complex class hierarchy).

  private static ThreadLocal< Integer > tls = new ThreadLocal<>();

  public static ThreadLocal< Integer > getTls() { return tls; }

  @Test
  public void test()
  {
    tls.set( 99 );
    int x = tls.get(); System.out.println( "  x = " + x );
    int y = tls.get(); System.out.println( "  y = " + y );

    tls.remove();
    tls.set( 543 );
    int z = tls.get(); System.out.println( "  z = " + z );

    tls.set( null );
    tls.set( 963 );
    int a = tls.get(); System.out.println( "  a = " + a );
    int b = tls.get(); System.out.println( "  b = " + b );
    tls.remove();

    int c = tls.get(); // kaBOOM!
  }

Output:

  x = 99
  y = 99
  z = 543
  a = 963
  b = 963

java.lang.NullPointerException
    at com.windofkeltia.tls.ThreadLocalTest.test(ThreadLocalTest.java:74)
    at java.base/jdk.internal.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
    at java.base/jdk.internal.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:62)
    .
    .
    .
    at org.junit.runner.JUnitCore.run(JUnitCore.java:137)
    at com.intellij.junit4.JUnit4IdeaTestRunner.startRunnerWithArgs(JUnit4IdeaTestRunner.java:69)
    at com.intellij.rt.junit.IdeaTestRunner$Repeater.startRunnerWithArgs(IdeaTestRunner.java:33)
    at com.intellij.rt.junit.JUnitStarter.prepareStreamsAndStart(JUnitStarter.java:220)
    at com.intellij.rt.junit.JUnitStarter.main(JUnitStarter.java:53)

Alternately, of course...

    ...
    int b = tls.get(); System.out.println( "  b = " + b );
    tls.remove();

    try
    {
      int c = tls.get();
    }
    catch( NullPointerException e )
    {
      System.out.println( "You can catch this." );
    }
  }

  x = 99
  y = 99
  z = 543
  a = 963
  b = 963
You can catch this.

Notes

• The thread-local store is created as static; there is no way to fetch a reference to it from the thread itself.
• To fetch it, you must either pass the static reference down or provide a static accessor (getter); code in any other class may freely manipulate the TLS' value including destroy it.
• As illustrated, once remove() or set( null) has been called, the store is gone for any practical use; you must not call get() without first resetting the value to something valid (as illustrated here).
• You should call remove() at some point before the thread is abandoned; if you don't, and your TLS resource is complex (i.e.: on the heap), you'll leak memory.

Useful if minimal set of methods to break a filesystem path up into usable bits.

Path path     = Paths.get( "src/test/resources/fodder/xml-samples/bundle.xml" );

Path filename = path.getFileName();      // bundle.xml
Path absolute = path.toAbsolutePath();   // /home/russ/dev/fhir-json-xml/src/test/resources/fodder/xml-samples/bundle.xml
Path parent   = path.getParent();        // src/test/resources/fodder/xml-samples
Path subpath  = path.subpath( 2, 4 );    // resources/fodder
int  count    = path.getNameCount();     // 6

System.out.println( parent.toString() ); // (prints:) src/test/resources/fodder/xml-samples

...or, in other words, the number of places it occupies, the length of an array or string needed to hold it, space in a table, etc.

Obviously, the most straightforward way would be to turn it into a string, then measure the latter's length, but that's very expensive. There are several other ways that are much cheaper. This one isn't the very least expensive, however, it rejoices in being the simplest and most succinct:

int number = (whatever);
int numberOfDigitsInNumber = ( int ) Math.log10( number ) + 1;

Example outcome:

                number = 4923
numberOfDigitsInNumber = 4

An Enumeration< String >, used for example, in conjunction with methods of HttpServletRequest, is a "one-shot collection" in terms of being able to be traversed.

Once traversed as below, ...

import java.util.ArrayList;
import java.util.Collections;
import java.util.Enumeration;
import java.util.List;
import java.util.NoSuchElementException;

import org.junit.Test;

public class EnumerationTest
{
  @Test
  public void test()
  {
    List< String > headerNames = new ArrayList<>();
    headerNames.add( "ContentType" );
    headerNames.add( "Accept" );

    Enumeration< String > headers = Collections.enumeration( headerNames );

    try
    {
      // traverse 'headers' to see what's in this collection...
      while( headers.hasMoreElements() )
        System.out.println( headers.nextElement() );

      // 'headers' is no longer useful for traversal--it is "dead" now
    }
    catch( IllegalArgumentException e )
    {
      e.printStackTrace();
    }
    catch( NoSuchElementException e )
    {
      e.printStackTrace();
    }
  }
}

...what's stored in headers can not be "reset" in order to get traversed again as there are only two useful methods, both used above, hasMoreElements() and nextElement(). If a more functional working copy is required, then create a List from it thus:

// take 'headers' from the code in the test above...
ArrayList headerNameList = Collections.list( headers );

for( String header : headerNameList )
  System.out.println( header );

// 'headerNameList' remains traversable after this point...

Both snippets of code here print the same output.

The premise is that you have a string that could have anything in it, but it likely has some digits. Let's say, "<2" or "0.5+" and you are interested in the numeric stuff. Use this to remove (the "<" and "+" from the examples here and infinite others):

final String VALUE          = (some example as above);
final String ONLY_NUMERICS  = VALUE.replaceAll( "[^\\d.-]", "" );

The result would be (for the two examples cited) "2" and "0.5".

"Renaming" XyzClass with XClass.

I have long wondered about "renaming" classes. In C, there is typedef that would allow me to use, for example, something called XyzPatient in my code as XPatient without me having to create a class formally.

#define IPatient IxmlPatient

In Java, I can do this:

Code from Xyz library:

public class XyzPatient
{
  public String name;

  @Override
  public String toString()
  {
    return "{ " + "name: \"" + name + "\" }";
  }
}

Code from my application's shim:

public class XPatient extends XyzPatient
{
}

Code from my application:

public class PatientTest
{
  @Test
  public void test()
  {
    XPatient patient = new XPatient();
    patient.name = "Jackson";
    System.out.println( patient );
  }
}

Formally speaking, this doesn't walk too far down the path of "decoration" for it only renames the class—it doesn't add anything to it. However, I have deceived you: I don't want to decorate the superclass with additional functionality, but only change its name.

Running test() produces:

{ name: "Jackson" }

But, I confess that I don't know how far this goes. I know that, in the past, I have had trouble doing much with class XPatient above. This example works well enough, but, when I have attempted to roll a class from a third-party library whose names I don't like (usually because they collide with classnames already in use in my code) into a "naked" decorator of this sort, I have had some trouble.

One problem I know about is when the extending class doesn't offer a constructor that matches one of the extended class' constructors. For example, let's conjecture a superclass, Pojo, underneath the library's XyzPatient, that offers an alternative constructor that we wish to make use of:

More complete code from Xyz library:

Note the non-default constructor. What's with toString()? just that XyzPatient.toString() uses Pojo.toString(), but lops off the last curly brace before adding its own field(s).

This example is a little stretched using field ____ to name the extending POJO, but it serves to complicate the example just enough to make it useful.

public class Pojo
{
  public String ____;

  public Pojo() { }

  public Pojo( final String elementName )
  {
    ____ = elementName;
  }

  @Override
  public String toString()
  {
    return "{\n  ----: \"" + ____ + "\" }";
  }
}

public class XyzPatient extends Pojo
{
  public String name;

  @Override
  public String toString()
  {
    StringBuilder sb   = new StringBuilder();
    String        base = super.toString();
    sb.append( "{ " ).append( base.substring( 0, base.length()-1 ) ) );
    sb.append( "name: \"" ).append( name ).append( name ).append( "\"\n" );
    sb.append( "}" );
    return sb.toString();
  }
}

Code from my application's shim:

public class XPatient extends XyzPatient
{
  public XPatient( final String name ) { super( name ); }
}

Code from application test:

Note the use of the non-default constructor.

public class PatientTest
{
  @Test
  public void test()
  {
    XPatient patient = new XPatient( "patient" );
    patient.name = "Jackson";
    System.out.println( patient );
  }
}

Running test() produces:

{
  ____: "patient"
  name: "Jackson"
}