State design pattern in Java

State design pattern is extremely useful when you need a state class. Typical example is a class making a connection to a server (check POP3 client tutorial for example). The class then has two states – connected and disconnected (which is the default state). In the class you would need to check for the state at many places. Let’s imagine that your class doesn’t have just two states but four or ten. You would find then many constructs similar to the following in your class:

public class Door {

private DoorStates state;

private void someMethod() {
// ....
switch (state) {
case CLOSED: // .....
case CLOSING: // .....
case OPENED: // .....
case OPENING: // .....
}
// ...
}

}

The main reasons for State design pattern are extensibility and simplification of the code.

Now I would like to tell you how to implement State designer pattern. The first thing you need to do is to figure out states which your class (let’s call it main class) can have. Let’s have a class handling a connection to a server. The class can certainly have states connected and disconnected. Each state is implemented using its own class (let’s call it state class) and all state classes have one identical ancestor (either interface or abstract class). In state class would be methods that behave differently in each state (the methods that would contain switch (state) { … } ). At first let’s see the main class:

public class Connection {

// state class instance reference
private ConnectionState state;

// list of all possible states
protected final ConnectionState CONNECTED = new ConnectionStateConnected(this);
protected final ConnectionState DISCONNECTED = new ConnectionStateDisconnected(this);

public Connection() {
// default state is disconnected
state = DISCONNECTED;
}

public void connect() {
state.connect();
}

public void disconnect() {
state.disconnect();
}

public boolean isConnected() {
return state.isConnected();
}

// called by a state class to set new state to this connection
protected void setState(ConnectionState state) {
this.state = state;
}

}

The first in the class is the state attribute that holds the actual state of the main class. Next attributes CONNECTED and DISCONNECTED are all possible states that the class can have. Please notice that they are protected. That is because of the state classes which need access them as you will see later. All state methods just delegate the call to the state class.

Now let’s see the ancestor of the all state classes:

public abstract class ConnectionState {

// childs need to have access to the connection instance too
protected final Connection connection;

public ConnectionState(Connection connection) {
this.connection = connection;
}

public abstract void connect();

public abstract void disconnect();

public abstract boolean isConnected();

}

Each state class has to implement the abstract class above. The only interesting thing is the connection attribute. A state class usually need somehow change state of the main class thus it has a main class reference so that the setState(…) method can be called in a state class.

I said that the connection class would have two states – connected and disconnected. We would then have two implementations of the abstract state class named ConnectionStateConnected and ConnectionStateDisconnected.

public class ConnectionStateConnected extends ConnectionState {

public ConnectionStateConnected(Connection connection) {
super(connection);
}

public void connect() {
throw new IllegalStateException("Already connected");
}

public void disconnect() {
// disconnect somehow

// finally set disconnected state of the connection instance
connection.setState(connection.DISCONNECTED);
}

public boolean isConnected() {
return true;
}

}

Please notice how the state class changes the state of the main class in disconnect() method.

public class ConnectionStateDisconnected extends ConnectionState {

public ConnectionStateDisconnected(Connection connection) {
super(connection);
}

public void connect() {
// connect somehow ...

// finally set connected state of the connection instance
connection.setState(connection.CONNECTED);
}

public void disconnect() {
throw new IllegalStateException("Already disconnected");
}

public boolean isConnected() {
return false;
}

}

You have to carefully figure out what to do if a state is called but it shouldn’t be. Example can be calling disconnect() method when there is no connection. You can either throw IllegalStateException or just log warning message wherever.

As you can notice … adding a new state is very simple task. You just add new child of the abstract state class, add new attribute representing the new state to the main class and that’s all.

You can download source codes here: http://rapidshare.com/files/126155409/stateDesignPattern.zip

How to call private constructor/method from outside in Java

As you certainly know, one of the OOP’s features is encapsulation. Java has private keyword to specify encapsulated constructors, methods or attributes. These methods and attributes should not be accessible from the rest of the world (they are not part of the API) and Java doesn’t allow you to do that ordinarily.

You can however use Java reflections API to access any private method, field or constructor of any class and it’s really very simple task. Let’s assume we have got the following simple class:


public class Test {

private Test() {
System.out.println("private constructor has been called");
}

private void test() {
System.out.println("private test() method has been called");
}

}

The class has private constructor and method (notice that such class is worthless because there is no way how to ordinarily get or create instance of it). Now I’ll show you how to get instance of the class using Java reflections and call the private method:


public class Main {

public static void main(String[] args) throws IllegalArgumentException, IllegalAccessException, InvocationTargetException, InstantiationException, SecurityException, NoSuchMethodException {

Class<Test> clazz = Test.class;

Constructor<Test> c = clazz.getDeclaredConstructor((Class[])null);
c.setAccessible(true); //hack
Test test = c.newInstance((Object[])null);

Method privateMethod = clazz.getDeclaredMethod("test", (Class[])null);
privateMethod.setAccessible(true); //hack
privateMethod.invoke(test, (Object[])null);
}

}

If you hadn’t called the setAccessible(true) method you would have got the java.lang.IllegalAccessException indicating that you call a method/constructor which is not meant to be called from outside.

Java reflections breaks OOP in many ways and you should very rarely use its “special” features like accessing private methods in your projects.

Java enum in Java Native Interface (JNI)

A few days ago I started to take interest in JNI (http://en.wikipedia.org/wiki/Java_Native_Interface). JNI is used to call java native methods that are written in other language than Java. Java native methods are usually system dependent and are used to provide functionality that has to be handled by an operating system. Example is creating and handling threads in Java. This functionality is system dependent and has to be handled directly by an operating system (let’s try to open and go through java.lang.Thread class source code in JDK). You can find very useful specification of JNI containing a few examples at http://java.sun.com/j2se/1.5.0/docs/guide/jni/. JNI provides many methods for manipulating Java primitive types, objects, exceptions, non-native methods and so long, but what is missing in the JNI guide is description how to manipulate enums in native code (implemented using e.g. C++) and that’s what I’m going to show you here (using C++).

Let’s assume we have got the following simple enum:

package test;

public enum MyEnum {
VALUE1, VALUE2, VALUE3;
}

Since Java version 1.5 enums are converted to ordinary Java classes so treat them is similar to any other Java object (I recommend you to decompile compiled MyEnum.class file). For the following native method declaration:

package test;

public class SomeClass {
public native String enumTest(MyEnum myEnum);
}

is then, using javah generator (it’s part of JDK, not just JRE), generated following C header:

JNIEXPORT jstring JNICALL Java_test_SomeClass_ enumTest(JNIEnv *, jobject, jobject);

The first parameter is pointer to Java environment, second is Java the object on which is the native method called and the third is the myEnum parameter (notice that the type is object). The way how to handle object in native code is a little bit similar to the Java reflections.

The first thing you have to do is to find the name of the method that returns actual "value" of the enum. You can find in the documentation (http://java.sun.com/j2se/1.5.0/docs/api/java/lang/Enum.html) that every enum has (among others) method name() that returns name of the value of the enum as String (the second usable method is ordinal() ). Now I’m going to show you how to call the name() method in native code implemented using C++:

JNIEXPORT jstring JNICALL Java_test_SomeClass_ enumTest(JNIEnv *env, jobject obj, jobject enumObj) {
jclass enumClass = env->FindClass("test/MyEnum");
jmethodID getNameMethod = env->GetMethodID(enumClass, "name", "()Ljava/lang/String;");
jstring value = (jstring)env->CallObjectMethod(enumObj, getNameMethod);
const char* valueNative = env->GetStringUTFChars(value, 0);
if (strcmp(valueNative, "VALUE1") == 0) {
printf("Enum has the VALUE1 value");
}
// ...
return NULL;
}

On the first line the pointer to the class is obtained using FindClass (http://java.sun.com/j2se/1.5.0/docs/guide/jni/spec/functions.html#wp16027) method. You should notice that package name is delimited by "/" and not by ".". On the second line the pointer to the correct method - name() is obtained using GetMethodID (http://java.sun.com/j2se/1.5.0/docs/guide/jni/spec/functions.html#wp16660) method. You have to provide correct method’s signature (look into the specification how to get correct method’s signature). The third line calls the method against given object. CallObjectMethod (http://java.sun.com/j2se/1.5.0/docs/guide/jni/spec/functions.html#wp4256) means that the method itself returns object (String). The fourth line converts returned string value from UTF-8 (which is used as encoding of strings in Java) to C encoding and finally the last line just compares obtained valued against one of the enum’s values.