Eclipse Neon will require Java 8

Excellent news from the Eclipse Foundation: the next version of Eclipse, called “Neon,” will require the Java 8 runtime. The announcement in email is underwhelming, but the actual project plan is a little more explicit and informative:

In general, the 4.6 release of the Eclipse Project is developed on Java SE 8 VMs. As such, the Eclipse SDK as a whole is targeted at all modern, desktop Java VMs. Most functionality is available for Java SE 8 level development everywhere, and extended development capabilities are made available on the VMs that support them.

Frank Vogella, in Eclipse Neon (Eclipse 4.6) will require a Java 8 runtime, says this:

Several Eclipse projects like m2e and Jetty have already moved to Java 8. This moves allows us in the Eclipse platform to use the improved Java 8 API to modernize and optimize our code base and will hopefully make the Eclipse project even more interesting for potential Eclipse contributors.
After all, who wants to work in his unpaid time with an outdated Java version?

From Apache: Log4J 1 end-of-lifed; update to Log4J 2 recommended

On 5 Aug 2015, the Apache Foundation announced that Log4J 1, the popular logging framework, has been end-of-lifed, meaning that no future releases are expected and maintenance and support have been discontinued.
Migration to Log4J 2 is enabled through the use of a Log4J 1.X bridge, as described in a short FAQ about the EOL of Log4J 1:

Q: Is there a way to quickly migrate from Log4j 1.x to Log4j 2.x?
A: Yes, you can use the Log4j 1.x bridge http://logging.apache.org/log4j/2.x/log4j-1.2-api/index.html You must use this bridge without Log4j 1 jars in your application’s classpath. The bridge forwards all requests to Log4j 1 to Log4j 2.

Which logging framework do you prefer, and why?

A set of testing tools

Petri Kainulainen posted “12 Tools That I Use for Writing Unit and Integration Tests,” which does a pretty good job of describing a set of testing tools and approaches, including solutions in the following categories:

  • Running Tests
  • Mock and Stub frameworks
  • Writing Assertions
  • Testing Data Access
  • Testing Spring

It’s not comprehensive (nor does it claim to be), with no mention of things like TestNG, Arquillian, Liquibase or Flyway, or testing CDI in general (see Arquillian), but that doesn’t mean it’s not a good start on an interesting idea. What tools would you suggest for testing?

Bypassing subclass method overrides

Someone in ##java recently asked a question that may come up with beginners to OOP: How to invoke a method of a superclass from the outside. For example, if ChildClass extends BaseClass and overrides BaseClass.method(), how can one invoke the method of the superclass, bypassing the override in ChildClass?
This is not a very good idea from an OOP standpoint, because the child class might not expect the parent’s behavior to be invoked, but it’s still a very interesting question. It turns out there actually is a way to do this, too.
We will work with the following class setup:

public class Test {
  public static class BaseClass {
    public String method() {
      return "BaseClass.method()";
    }
  }
  public static class ChildClass extends BaseClass {
    @Override
    public String method() {
      return "ChildClass.method()";
    }
  }
}

In Java bytecode, normal (not static, not an interface) method calls are made via the invokevirtual instruction. (As an example, invokevirtual is used when doing a simple obj.method() call.) However, this obviously will not work for super.method() instructions in code – the overridden method, not the superclass’ method, would be called. For this purpose, the JVM has another invoke instruction called invokespecial: it is used to invoke an instance method of an exact class, without respecting overridden method definitions.
Sadly, the verifier complains when we try to do load a class that does this; it throws a VerifyError with the message Illegal use of nonvirtual function call. The invokespecial instruction on a method can only be used from a direct subclass or the class itself, in the places where you would expect super.method() to work (inner classes use a bridge method). It’s probably better this way, too – if this was possible without some security checks, this could probably be easily exploited.
Method handles to the rescue! With the introduction of the MethodHandles API in Java 7, we have all sorts of nifty ways to bypass such measures through a bit of reflection. This API is also protected by access checks – here throwing IllegalAccessExceptions when we try to create our invokespecial handle.

Editor’s note: Java 7 has been end-of-lifed as of this writing – you should be using Java 8 by now, unless you have specific requirements holding you back to an older version of Java.

This is fairly easy to bypass by using normal reflection to create an instance of MethodHandles.Lookup that has a “Lookup Class”, meaning the permissions of a class, that is in fact allowed to invokespecial our target method BaseClass.method(). There are two candidates for this: the direct subclass of BaseClass, in our example ChildClass (for those super.method() calls mentioned above), and BaseClass itself (for some constructor business). For convenience we will use BaseClass as getting the direct child class requires a few more lines of code:

Constructor<Methodhandles.Lookup> methodHandlesLookupConstructor =
  MethodHandles.Lookup.class.getDeclaredConstructor(Class.class);
methodHandlesLookupConstructor.setAccessible(true);
MethodHandles.Lookup lookup = methodHandlesLookupConstructor.newInstance(BaseClass.class);

Now the fun begins! We can use MethodHandles.Lookup.findSpecial() to create a MethodHandle that points towards our target method. We don’t need to worry about access checks here due to the constructor code above:

MethodHandle handle = lookup.findSpecial(
  BaseClass.class, "method", MethodType.methodType(String.class), BaseClass.class);

Done! Working example:

import java.lang.invoke.MethodHandle;
import java.lang.invoke.MethodHandles;
import java.lang.invoke.MethodType;
import java.lang.reflect.Constructor;
public class Test {
  public static void main(String[] args) throws Throwable {
    ChildClass obj = new ChildClass();
    System.out.println(obj.method()); // prints ChildClass.method()
    System.out.println(invokeSpecial(obj)); // prints BaseClass.method()
  }
  static String invokeSpecial(BaseClass obj) throws Throwable {
    // create the lookup
    Constructor<MethodHandles.Lookup> methodHandlesLookupConstructor =
      MethodHandles.Lookup.class.getDeclaredConstructor(Class.class);
    methodHandlesLookupConstructor.setAccessible(true);
    MethodHandles.Lookup lookup = methodHandlesLookupConstructor.newInstance(BaseClass.class);
    // create the method handle
    MethodHandle handle = lookup.findSpecial(
      BaseClass.class, "method", MethodType.methodType(String.class), BaseClass.class);
    return (String) handle.invokeWithArguments(obj);
  }
  public static class BaseClass {
    public String method() {
      return "BaseClass.method()";
    }
  }
  public static class ChildClass extends BaseClass {
    @Override
    public String method() {
      return "ChildClass.method()";
    }
  }
}

Link: Jenkins over HTTPS with JNLP slaves

A user in ##java recently ran into a problem where he needed to connect Jenkins slaves to a master, using SSL – and it didn’t work, thanks to security. He helpfully wrote up how using correct policy files got it working.
Jenkins is a continuous integration server – basically an application that runs your builds when changes occur in your source tree. Slaves allow the build to take place on different hardware configurations, as well as providing horizontal scalability to your builds.
Good stuff, and thanks!

Deep Dive: All about Exceptions

Overview

Exceptions are a mechanism for java code to signal extraordinary conditions (such as virtual machine errors like running out of memory, code bugs such as passing a negative number to a method that doesn’t accept negative numbers, alternative ways a method can exit, such as an attempt to read from a network socket aborting because the other end severed the connection, and even intentional control flow such as aborting a thread ASAP). They are similar to signals, if you are familiar with that concept.

Basic mechanism

Exceptions can be thrown anywhere in Java code.
When an exception is thrown, the currently executing line of code is aborted, and the JVM checks if the currently executing line of code is inside of a try block that has an associated catch block that catches the exception (this is known as the exception handler block). If an associated exception handler block exists, execution continues in that block, and the act of throwing the exception is effectively equivalent to break whatever loops you need to break and then go to the exception handler immediately.
If there is no exception handler, the entire method is aborted immediately (the method exits immediately), and the exception ‘bubbles up’ to the next method in the call stack (the method that called the method that just aborted). The process then repeats: Either the caller of the method that threw the exception has an exception handler for it, in which case execution continues there, or it does not, and this method, too, is aborted and now the method that called the method that called the method that threw the exception gets its chance.
This process continues all the way up to the JVM if no code on the call stack has an appropriate exception handler. At the top level, the thread itself will stop execution and echo the exception class name, associated message, stack trace, etc to System.err.

Throwing exceptions

To throw an exception, you use the throw statement, like so:

throw new IllegalArgumentException("foo should be positive");

When throwing an exception, you should usually add a convenient message explaining the situation in plain English, without ending the sentence in a full stop. You don’t have to create a new instance of an exception, but 99+% of the time you throw an exception, you create a new one like in the example. The aim of throwing an exception is usually to abort this method and signal to the caller that the method has finished executing with an unexpected result. In this sense, throw is a lot like return.

Catching exceptions

To catch an exception, you use the try/catch block, like so:

try {
    someMethodThatMightThrowAnException();
} catch (IllegalArgumentException e) {
    // handle the issue here.
}

You can add multiple catch blocks to a single try, each catching a different exception type. If an exception does occur in the body of the try block, the first exception handler whose catch line lists an exception type that matches the thrown exception ‘wins’ and code will resume execution there.
If you’re using Java 1.7 or newer (as you should be), you can also list multiple exception types for a single catch block. For example:

try {
    someMethodThatMightThrowAnException();
} catch (IllegalArgumentException | NullPointerException e) {
    // handle either of those exceptions here.
} catch (IOException e) {
    // And handle I/O issues here.
}

The exception type hierarchy

All things that you can throw or catch must either be the type java.lang.Throwable or a subtype of it. There are 4 major types you should be aware of:

java.lang.Error

A subclass of Throwable, Error is used to communicate serious, generally unrecoverable problems with the hardware or JVM itself: the system is out of memory, the jar file containing your classes is corrupt, or you’ve got a method that endlessly calls itself, and the stack has overflowed.
You should generally never throw any Errors yourself, with the possible exception of InternalError which you can throw if a JVM guarantee fails to hold (for example, the JVM specification guarantees that UTF-8 is an available character encoding. If it isn’t, you can throw InternalError).
You should subclass Error and throw it if an invariant is broken that can only be explained by a corrupt installation or failing hardware, such as when you read a data file via .getResourceAsStream that’s packed along with your code, and it’s not there. That’s as catastrophic as a missing class file, which are also handled with errors.
Error, and all subclasses of Error, are so-called ‘unchecked exceptions’ (see below). You rarely catch them.
Note that some errors may not have reliable stack traces, and some (most notable OutOfMemoryError) may indicate the JVM has become unstable.
The usual strategy to handle an Error is to just let the JVM crash. Most Errors thrown in java applications result in the application crashing entirely, and this is intentional, because the problem cannot be solved.

java.lang.Exception

The only other subclass of Throwable in the java.* namespace, this one indicates a more or less ‘expectable’ problem. Anything from unexpected user input to failing network connections to invalid SQL statements – they are generally handled by throwing some subclass of j.l.Exception. You should never throw Exception itself (always a more suitable subclass, and if no such suitable subclass exists, make your own), and, like j.l.Error, don’t catch it unless you are some sort of app server and you’re the final line of defense against a failing servlet, applet, event handler, etc.

Editor’s Note: This is a Java-centric concept; other JVM-based languages like Scala are far less restrictive in how exceptions are handled. Which approach is better for you depends very much on what you’re comfortable with. Using Java’s more restrictive approach is hardly ever a bad thing, but some other languages’ communities look down on it.

java.lang.RuntimeException

This is a subclass of java.lang.Exception and covers a mix of code bugs and unexpected and generally unfixable problems.
Examples (all mentioned exceptions in this list are subclasses of RuntimeException):

  • Whenever you write x.foo in java, and x is null, the line throws a NullPointerException.
  • Many methods will throw IllegalArgumentException if you for example pass a negative number to a method that expected only positive numbers.
  • If you try to refer to an array element that is outside of the bounds of that array, an ArrayIndexOutOfBoundsException is thrown. For example: int[] x = new int[10]; print(x[11]);

Like Error, RuntimeException and all subclasses of it are so-called ‘unchecked’.
The usual strategy to handle RuntimeExceptions depends on the exception; for exceptions that signify that you programmed a bug, the appropriate resolution is to just crash the application; the stack trace serves as debugging tool. There are also many runtime exceptions that occurr because of invalid user input (the user entered a word where they were supposed to enter a number) or some other problems for which you can write a resolution; you should catch those.

java.lang.Throwable

This gets us back to Throwable itself. You can subclass it, but you should only do that when you use exception as control flow, which is not something you should think about until you have outgrown the need for articles such as these. Until you know a lot better, don’t ever subclass Throwable itself.

Editor’s note, because it bears repeating: You can subclass Throwable, but you should only do that when you use exception as control flow, which is not something you should think about until you have outgrown the need for articles such as these. Until you know a lot better, don’t ever subclass Throwable itself.

Checked vs. Unchecked

As the previous paragraph explained, java.lang.Error and java.lang.RuntimeException, and all subclasses of those two, are known as the ‘unchecked exceptions’. The rest are checked. Those 2 classes are special and listed by name in the Java language specification. You can’t make more unchecked exceptions without subclassing Error, RuntimeException, or some other class that is itself a subclass of one of these two.
Checked exceptions MUST be handled in one of two ways:

  • You wrap the code that is declared to possibly throw one in a try/catch block which catches the checked exception in question, -OR-
  • The method with the code that is declared to possibly throw one, has a ‘throws’ clause that explicitly declares that it throws this exception.

In other words, if you’d like to write throw new IOException("Network connection lost"), then your method signature has to look like: public void myMethod() throws IOException. (IOException is a checked exception). Now code that calls myMethod inherits the requirements to handle it somehow: Either wrap the call to myMethod() in a try/catch block, or also put throws IOException in the method declaration line.
For unchecked exceptions, you have no such requirements. As such, you can throw them without adding that exception to the throws clause. In other words, all methods in all of Java, whether they are specified to do so or not, implicitly act like they have throws Error, RuntimeException tacked onto them. You can add throws NullPointerException to your method declaration if you like; this is meaningless (as NullPointerException is a subtype of RuntimeException and thus unchecked) but some programmers do this as a way to document their code.

Features of Throwable

Stack traces

Whenever any throwable object is created (with new, such as new FileNotFoundException()), the call stack (the chain of method invocations) is stored in the object you just made. A call stack looks something like this:

java.lang.FileNotFoundException: /foo/bar/baz (No such file or directory)
    at java.io.FileInputStream.open(Native Method)
    at java.io.FileInputStream.<init>(FileInputStream.java:138)
    at java.io.FileInputStream.</init><init>(FileInputStream.java:93)
    at Example.main(Example:8)

The actual exception was thrown (with a throw statement) inside the top listed method. That method was invoked by the constructor of FileInputStream, on line 138, that constructor was invoked by another FileInputStream constructor, and that constructor was invoked by our example code.
You can programatically browse the call stack using the .getStackTrace() method of Throwable. Default handlers of execution frameworks will print them to logs or the screen so you can review the problem.
ADVANCED TOPIC: If you wish to ‘save’ a stack trace (for example, because in a different thread at a later time, a problem will surface that was initially caused by the current invocation, but we don’t know yet if that will happen, so we wish to save the stack trace for now and possibly refer to it much later if failure does eventually happen), just create a new exception without actually throwing it (yet).

Cause

Often the right approach to handling an exception is to restate the problem in your own exception type, and with a more appropriate message. It helps to staple the original cause to this brand new exception. This is called the ’cause’ and can be attached via the initCause() method. Also, most exception types have a constructor that takes the cause if you have one. The cause will be logged/printed along with the new exception.
Make sure you add the appropriate cause if there is one; it really helps debug issues and figure out what went wrong.

Which exception should I throw?

Before we start, be aware that Java has been around for a long time and believes strongly in not changing already released code. As such, you can find many examples of methods throwing the ‘wrong’ kind of exception in java.* and popular libraries. That’s not ‘proof’ that their style is accepted convention or a good idea.

  • A method must list each checked exception that it might possibly throw, and calling code must then handle it somehow (either with a try/catch block, or by adding a throws clause to the method, passing on the burden of handling the issue to all callers of this method). This is very annoying if the method is ever invoked such that the checked exception couldn’t possibly occur (in the sense of: Having to write code that is literally pointless, therefore impossible to test, and aggravating the author of the code calling yours). Therefore, for all problems that can only occur for invalid input or due to conditions entirely under control of the caller, ALWAYS use unchecked exceptions, that is: subtypes of RuntimeException.
  • The type of the exception is the most important tool that you can give to callers of your code to handle the issue. Therefore, the more likely it is that you expect callers of your method to try/catch your exception, the more important it is to throw an appropriate type. Often, this means you should make your own type. Don’t shy away from this; making your own type (writing public class MyOwnException extends Exception {... in MyOwnException.java) is usually a good idea. When in doubt, make your own exceptions.

  • When different issues can come up but they are related in some way, especially if you expect that a caller might just want to handle all these issues in the exact same manner, you should build an exception hierarchy: One overarching type, with various subtypes of that type for more details. For example, java.io.FileNotFoundException is a subtype of java.io.IOException, which is a subtype of java.lang.Exception. If you call any method that may fail due to a file not existing, then FileNotFoundException may occur. You can catch this condition with catch (FileNotFoundException e) {...}, but if you don’t write such a catch block but you do catch all I/O problems with catch (IOException e) {...}, then all file not found problems will also be handled by this more general catch block. This is good API design: You give your caller the flexibility to handle issues as specifically, or as generally, as is appropriate for them. Make hierarchies of exception types if that is applicable.

  • The more likely a problem signaled via an exception can be handled in some appropriate way (other than ‘just crash the application or abort the web request’), the more you should lean towards a checked exception. The more likely a problem cannot be feasibly handled other than by aborting the entire operation, the more you should lean towards an unchecked exception. After all, a checked exception enforces the caller to deal with it, which is just pointless boilerplate if it is highly unlikely that the programmer that calls your method can do anything useful if the problem does occur.

Examples:

  • To signal that the caller provided invalid input arguments, use RuntimeException subtypes. A few common ones already exist:
    • NullPointerException is appropriate if an argument is null and that is not valid input. The message of the exception should be the name of the argument: if (foo == null) throw new NullPointerException("foo");
    • IndexOutOfBoundsException is appropriate when an index is passed that is out of the valid range.
    • IllegalStateException is appropriate if the object is in a state such that this method call isn’t valid at all. For example, a List class has been ‘locked’ and later a caller attempts to add another object to it.
    • UnsupportedOperationException is appropriate if the object is in a state such that the call isn’t valid, and the object has always been, and will always be, in this state. For example, the add method of a list that is designed to be immutable (all objects that are in it are added during its construction and the list will never change) should throw UnsupportedOperationException.
    • Various other types exist, but if you can’t find anything more appropriate, there’s always IllegalArgumentException. Because these are almost always bugs, you don’t need to make a specific subtype (under the rule: “the less likely it is that callers intend to catch it, the less need there is to make a subclass for it”).
  • To signal I/O errors, be it because of disk failure, network connection failure, or something more exotic, like failure to communicate with a device plugged into a serial port, throw java.io.IOException. You rarely throw it yourself though; you use APIs that talk to networks (such as HttpServletResponse, or Socket) and the API will throw the IOException for you.

A few examples where common libraries actually got it wrong:

  • NumberFormatException is thrown by Integer.parseInt(), Long.parseLong(), etcetera; these methods parse text input for a number and return it. The exception is thrown if the text passed to the method is not, in fact, a number. This error is both to be expected (users can make mistakes; if talking to another software product, it might be buggy or on some different version), and often handleable, and yet NumberFormatException is a runtime exception. I/O issues are in fact somewhat less recoverable and somewhat less expectable, and yet those are checked exceptions, which is inconsistent.
  • Various methods in the JDK take a string that represents the character encoding. For example, when turning an array of bytes into a string, you should pass in the name of the text encoding that it used. Certain encoding types such as UTF-8 are guaranteed by the Java virtual machine specification to always be available. Still, this code: new String(someByteArray, "UTF-8") is specced to throw UnsupportedEncodingException, which is a checked exception. That exception couldn’t possibly occur unless your JVM is corrupt (at which point you have far bigger problems). Fortunately this has been ‘solved’ in later versions by way of a method specifically designed for calling with known-valid charset names (new String(someByteArray, StandardCharsets.UTF_8)).

  • @SneakyThrows

    Project Lombok is a compiler plugin that adds the ability to ‘ignore’ the rule that you must either try/catch, or declare that you ‘throws’ a checked exception, by annotating your method with @SneakyThrows(IOException.class) for example. This is particularly useful for working around unwieldy APIs, such as the UnsupportedEncodingException example listed above.

    Editor’s note: I heartily endorse the use of Lombok, whose author contributed this article. I rarely work on any Java projects without it now.

    The ‘default’ exception handler

    Some IDEs and many examples use the following default implementation for an exception handler:

    try {
        // Code that throws some exception
    } catch (IOException e) {
        e.printStackTrace();
    }
    

    This is a really bad default! You miss the message and the type of exception, and, more importantly, the code will just continue running immediately following the catch block. Most likely another exception will occur soon (given that clearly something is wrong, and in addition a bunch of your code, namely everything in the try block from the place where the exception occurred and onwards) also did not run. If that exception is handled similarly, yet another exception will occur soon. You’ll be faced with a cavalcade of stack traces, most of which are complete red herrings. Your app is also now completely broken, as code continues to execute even though your method has failed and its state is most likely no longer valid.
    Don’t do this!
    The single best default exception handler looks like this:

    try {
        // Code that throws some exception
    } catch (IOException e) {
        throw new RuntimeException("XXTODO: Uncaught", e);
    }
    

    The exception text makes no bones about it: You’ve intentionally decided not to worry about this exception right now. Your method will also abort instead of continuing to run in an invalid state, and you can throw RuntimeException without having to add a throws clause.

    How to make your own

    If no exception exists that exactly describes the issue you are attempting to signal to your method’s callers, or it is unchecked when you want it to be checked or vice versa, you have to make your own. Fortunately, it is very easy to do this. For example, to make a new unchecked exception, you would write:

    public class MyException extends RuntimeException {
        public MyException(String msg) {
            super(msg);
        }
        public MyException(String msg, Throwable cause) {
            super(msg, cause);
        }
    }
    

    Use a more descriptive name than MyException, of course. You can extend any existing class. If there’s no existing class that seems to make sense, extend Error, Exception, or RuntimeException depending on what kind of exception you want to create.

    The finally construct

    Sometimes you want code to execute to close resources or bring your object back to a valid state, and you want this code to run even if the main body of your method exits via an exception. The finally construct can help here. It’s part of the try syntax, and looks like:

    try {
        // code that might throw an exception
    } catch (NumberFormatException e) {
        // Runs if NumberFormatException occurs in body.
    } finally {
        // Runs always
    }
    

    In the above example, the code in the finally block is always executed. If the main body (or the catch handler) uses the return statement, your finally code runs right before your method returns. If the try block just gets to the end naturally without an exception occurring, execution jumps to the finally block. If a NumberFormatException occurs, execution jumps to your NumberFormatException catch handler, and after that handler has completed (or if that handler itself throws an exception), your finally block is executed. If some other exception occurs in the try body, then code execution first jumps to your finally block, and once that finishes, the exception is actually ‘thrown’ (execution jumps to the caller and the exception is raised there).
    If your finally block also explicitly exits the method (either via a return statement, or a throw statement), it overrides the explicit method exit that caused your finally block to run. Because that gets very confusing, you should not use return or throw in a finally block.
    A try block needs to have either a catch block or a finally block, or it wouldn’t do anything. However, you don’t need both; just try {} finally {} is valid, for example.
    NB: If a method never exits, for example because it loops endlessly or it has deadlocked, then the finally block would never execute. Also, if the JVM is shut down, either normally (with System.exit(0) for example), or forcibly (killed by the OS, or someone trips over a power cable), your finally blocks don’t run either.

    Automatic Resource Management (‘ARM’)

    Closing resources is a common pattern: Many classes, such as for example java.io.FileInputStream, are specified to require the caller of the constructor to eventually call close() on the stream. Failure to do so means the VM will leak resources, and, eventually, it can’t open any more files and the only solution is to restart the VM. Just calling close() when you are done is not sufficient because exceptions exist: You need to use a finally block. Because this is such a common pattern, there’s an easier way to do it, which is legal Java starting with Java v1.7:

    try (FileInputStream in = new FileInputStream(path)) {
        // code goes here; it can access 'in'
    }
    

    In the above snippet, no matter how execution exits the try block (via return statement, by running to the end of it, or via an exception), the resource will be closed.
    Another option is to use project lombok:

    @lombok.Cleanup FileInputStream in = new FileInputStream(path);
    // code goes here
    

    Here, ‘in’ will be closed when it goes out of scope, for example at the end of the method, no matter how it exits. Lombok’s cleanup works from java v1.6 and up. For more information, see the lombok feature page on @Cleanup.

    How ‘checkedness’ is javac only.

    The concept of checked exceptions are twofold:

    • You cannot catch a checked exception unless at least one thing in the associated try block is declared to throw that exception.
    • If any line is declared to throw a checked exception, then this line must exist either inside of a try block with an associated catch handler for this checked exception, or, the method it is in must have declared this checked exception in its throws line.

    However, these 2 rules are applied only by the Java compiler (javac). The actual JVM treats all exceptions as unchecked; bytecode that throws a checked exception without declaring it does so / catching it, will run just fine, and, at the bytecode level, you can have a catch handler for a checked exception that can’t actually occur and the JVM will run it. This is why other languages that also compile to class files but which don’t have checked exceptions can work at all, and it’s also what makes lombok’s @SneakyThrows tick.

    Finding hash collisions in Java Strings

    In ##java, a question came up about generating unique identifiers based on Strings, with someone suggesting that hashCode() would generate generally usable numbers, without any guarantee of uniqueness. However, duplicate hash codes can be generated from very small strings, with ordinary character sets – see this stackoverflow answer – and therefore I thought it’d be interesting to find other short strings with the same hash values.
    It was discussed how prone to collisions the Strings hashCode() method is, especially when using small strings. You would naturally assume a hashCode with an int as result – and thus 2 billion possible values – will be unique for small and simple strings.
    Here’s a simple class to demonstrate this:

    package org.javachannel.collisions;
    import java.util.ArrayList;
    import java.util.HashMap;
    import java.util.List;
    import java.util.Map;
    import java.util.Map.Entry;
    /**
    * Simple example class to show amount of hashCode collisions in Strings.
    *
    * TODO: Make the number of characters and the character set to be more
    * configurable
    *
    * @author Michael Stummvoll
    */
    public class HashCodeCollision {
      public static void main(String[] args) {
        Map<Integer, List<String>> hashMap = new HashMap<>();
        String str = "abcdefghijklmnopqrstuvwxyz";
        str += str.toUpperCase();
        for (char c1 : str.toCharArray()) {
          for (char c2 : str.toCharArray()) {
            // for (char c3 : str.toCharArray()) {
            String s = c1 + "" + c2; // + "" + c3;
            int code = s.hashCode();
            if (!hashMap.containsKey(code)) {
              hashMap.put(code, new ArrayList<String>());
            }
          hashMap.get(code).add(s);
          // }
        }
      }
      int collisions = 0;
      int max = 0;
      List<String> maxList = null;
      for (Entry<Integer, List<String>> e : hashMap.entrySet()) {
        List<String> l = e.getValue();
        if (l.size() > max) {
          max = l.size();
          maxList = l;
        }
        if (l.size() > 1) {
          System.out.println("Collision: " + l);
          ++collisions;
        }
      }
      System.out.println("collisions found: " + collisions);
      System.out.println("biggest collision: " + maxList);
      }
    }

    This reveals that in all permutations of 2 letter strings consisting of letters we already have 1250 collisions (with two strings for each given hash code). When using 3 letter strings, we’d see that we have 37,500 collisions with up to four strings per hash code.
    When reviewing the implementation of String‘s hashCode() method, you can conclude that it’s very easy to provoke collisions both ways, both intentionally and accidentally. So you shouldn’t rely on hash codes being unique for your Strings.

    First steps: Structure of your first source file

    This is what a class file ought to look like when you take your first steps writing java programs:

    public class YourAppNameHere {
      public static void main(String[] args) {
        new YourAppNameHere().go();
      }
      private String iAmAField;
      void go() {
        System.out.println("Your code goes here!");
      }
      void someOtherMethod() {
        // You can call this method from 'go' with: someOtherMethod()
        iAmAField = "Hello, World!";
      }
    }

    In particular, copy/paste the main() method verbatim and don’t touch it. If you need access to the command line arguments, pass the args parameter directly to your go method, and update the go method to take String[] args as parameter.

    Editor’s note: Another way of handling arguments is to use JCommander, which itself encourages the kind of object design in this post.

    Why should you do it this way? The short answer is: Because main() has to be static, but the idea of static is advanced java. You will and should learn about it in time, but trying to explain it to you (so that you don’t make mistakes because you don’t understand what that means) as you take your first steps is a bit like teaching you about the fuel gauge during your first drive. It’s just not that interesting, and you don’t need to know about it to start taking your first steps. It’ll become much more obvious once you’ve done some exercises. This main() method will get you out of static immediately so that you can ignore its existence until the time comes to learn about what it’s for.

    Guava's Equivalence: strategy for equals()/hashCode()

    Introduction

    Given a class C, if you want to implement ordering, you have two choices:

    1. Have your class implement Comparable<c> (or Comparable<x>, where X is a superclass of C).
    2. Define a Comparator<c> to use with this class (or a Comparator<x>, where X is a superclass of C).

    In fact, many classes in the JDK will have you supply a Comparator if your class does not implement Comparable; examples include Collections.sort() and Arrays.sort().
    It can be said that for a given class C, a Comparator defines a strategy for ordering, and that you need to supply a Comparator if the class itself does not define this strategy (that is, does not implement Comparable).
    And while the JDK offers a means to provide different strategies for ordering, it does not do so for a more fundamental contract of Object: equals() and hashCode().
    And this is where Guava comes in.

    Equivalence: a strategy for Object’s `equals()` and `hashCode()`

    Guava’s Equivalence intends to fill this gap. In the same vein as a Comparator, using an Equivalence allows you to either define a different equals()/hashCode() strategy than the one already defined by your target class, or to define one for a target class which “has none at all” (meaning, in this case, that the class uses Object‘s equals()/hashCode() implementations).

    Usage part 1: implementing an Equivalence

    Equivalence is a parameterized class; for a class C, you will need to implement two methods:

    • doEquivalent(C a, C b): given two instances a and b of class C, are those two classes considered equivalent? This is really like writing an implementation of equals() for class C, except that you don’t have to handle nulls (it is guaranteed that both parameters are non-null) nor casts (it is guaranteed that both arguments are “at least” of type C).
    • doHash(C t): given an instance t of class C, compute a hash value. Of course, an implementation must mirror Object‘s hashCode()/equals() contract: if doEquivalent(a, b) is true, then doHash(a) == doHash(b).

    Note that it is guaranteed that arguments to these methods will never be null.

    Usage part 2: “out of Collections” usage

    There is really only one method you will need here: .equivalent(). Provided you want to test equivalence between two instances of a given class C, you will do:

    final C a = ...;
    final C b = ...;
    final Equivalence<C> eq = ...;
    // Test equivalence of a and b against equivalence stragey eq
    if (eq.equivalent(a, b)) {
        // Yup, they are
    }

    Usage part 3: Collection usage

    Unlike the Comparable/Comparator relationship, equivalence between objects has to be “engraved” into collections. This unfortunately means that the syntax to initiate a collection is somewhat on the verbose side. Namely, if you want to initiate a Set of elements of class C wrapped into an Equivalence, you will have to initialize it as such:

    // Java 7 and better...
    Set<Equivalence.Wrapper<C>> set = new HashSet<>();
    // Java 5 or 6; and since we use Guava...
    Set<Equivalence.Wrapper<C>> set = Sets.newHashSet();
    

    You will also need to rely on an Equivalence implementation in order to interact with this collection (of course, you also need to ensure that you use the same implementation all along!):

    // Your Equivalence...
    Equivalence<C> eq = ...;
    // Inserting an element c into a Set<Equivalence.Wrapper<C>> set
    set.add(eq.wrap(c));
    // Removing, testing...
    set.remove(eq.wrap(c));
    set.contains(eq.wrap(c));
    // Retrieve the original element
    C element;
    for (final Equivalence.Wrapper<C> wrapped: set) {
        // get the original element
        element = wrapped.get();
        // do something with element
    }

    Conclusion

    Admittedly, having to redefine an equivalence strategy is far less common than having to redefine an ordering strategy. It is, however, a welcome tool to use when you have to deal with a “foreign” class which doesn’t meet your equals()/hashCode() expectations, either because there is no implementation at all for this class, or because the existing implementations don’t suit your needs.
    Happy coding!

    PriorityQueue and mutable item behavior

    From today, in Java: a user asked if changing the value of an item in a PriorityQueue would still result in the queue being correctly ordered. (He explained that he was doing this to prioritize based on counters, which makes sense. It’s worth noting that this blog entry is not about solving his problem, but about the behavior of PriorityQueue.)
    Getting items out of a PriorityQueue requires peek() and/or poll(). Let’s take a look at some simple usage; first, let’s look at an object that represents something with a priority:

    class Container implements Comparable {
      int x;
      public Container(int x) { this.x = x; }
      public int getX() { return x; }
      public void setX(int x) { this.x = x; }
      @Override
      public String toString() { return "Container{" + "x=" + x + '}'; }
      @Override
      public int compareTo(Container o) {
        return Integer.compare(getX(), o.getX());
      }
    }

    Let’s use this from another class. First, a utility method that builds a Queue, returning one element from the Queue for us to mutate later:

    private static Container buildQueue(Queue q) {
      q.clear();
      q.add(new Container(4));
      q.add(new Container(2));
      q.add(new Container(6));
      Container c = new Container(5);
      q.add(c);
      return c;
    }

    As stated, we need to use peek() or poll() to get results out in correct order. If we use normal iteration, our order starts off correctly, but fails immediately. Here’s the code:

    buildQueue(q);
    for(Container c1:q) {
      System.out.println(c1);
    }

    And the output is:

    Container{x=2}
    Container{x=4}
    Container{x=6}
    Container{x=5}

    The first element is in the right place – we expect 2 as the highest priority – but the others are in insertion order, not actual priority order.
    If, however, we use poll(), we get different results. The code:

    buildQueue(q);
    while((c=q.poll())!=null) {
      System.out.println(c);
    }

    And the output:

    Container{x=2}
    Container{x=4}
    Container{x=5}
    Container{x=6}

    What poll() does is simple: it removes the head of the Queue – the item with priority – and then it sifts the queue, with the result that the Queue‘s order is adjusted. Depending on the nature of the queue, this may put it in proper order all the way through the queue, but this is not required — the actual result is that the Queue is more ordered, with the new head of the Queue (the result of the next poll() or peek()) being set properly.

    If you want to see the actual code for this process, grepcode has it: see PriorityQueue.poll(). Internally, “sift” is the actual term used.

    Mutating the Elements in the Queue

    What happens if we mutate the priority, then?
    As it turns out, the behavior of the Queue doesn’t change much – except that the results of the last sifting of the Queue are maintained. This is actually a big deal. poll() doesn’t sift the Queue before returning the head of the queue. Therefore, if this is our code:

    Container container = buildQueue(q);
    System.out.println("1: "+q);
    container.setX(3);
    System.out.println("2: "+q);
    while((c=q.poll())!=null) {
      System.out.println(c);
    }
    
    1: [Container{x=2}, Container{x=4}, Container{x=6}, Container{x=5}]
    2: [Container{x=2}, Container{x=4}, Container{x=6}, Container{x=3}]
    Container{x=2}
    Container{x=3}
    Container{x=4}
    Container{x=6}

    Note what happens: we modify the last element in the Queue to be 3, and the Queue maintains its order, but pulling the results out via poll() gives us the results as we expect. But if we change the priority of the last element such that it should be first… let’s see what that looks like.

    container = buildQueue(q);
    System.out.println("1: "+q);
    container.setX(1);
    System.out.println("2: "+q);
    while((c=q.poll())!=null) {
      System.out.println(c);
    }

    Our output is:

    1: [Container{x=2}, Container{x=4}, Container{x=6}, Container{x=5}]
    2: [Container{x=2}, Container{x=4}, Container{x=6}, Container{x=1}]
    Container{x=2}
    Container{x=1}
    Container{x=4}
    Container{x=6}

    Summary

    As stated, PriorityQueue sifts its values after pulling the top element from the Queue. It’d be unwise to expect a Queue to work properly with mutable items in any case – much as using mutable keys in a Map would be unwise – but as you can see, mutating the priorities can work but can also fail if you happen to modify the priorities such that the element at the head of the list should change.