We have basic java comments infrastructure using which we add information about the code / logic so that in future, another programmer or the same programmer can understand the code in a better way. Javadoc is an additional step over it, where we add information about the class, methods, variables in the source code. The way we need to add is organized using a syntax. Therefore, we can use a tool and parse those comments and prepare a javadoc document which can be distributed separately.

Javadoc facility gives option for understanding the code in an external way, instead of opening the code the javadoc document can be used separately. IDE benefits using this javadoc as it is able to render information about the code as we develop. Annotations were introduced in JDK 1.5

Uses of Annotations

Annotations are far more powerful than java comments and javadoc comments. One main difference with annotation is it can be carried over to runtime and the other two stops with compilation level. Annotations are not only comments, it brings in new possibilities in terms of automated processing.

In java we have been passing information to compiler for long. For example take serialization, we have the keyword transient to tell that this field is not serializable. Now instead of having such keywords decorating an attribute annotations provide a generic way of adding information to class/method/field/variable. This is information is meant for programmers, automated tools, java compiler and runtime. Transient is a modifier and annotations are also a kind of modifiers.

More than passing information, we can generate code using these annotations. Take webservices where we need to adhere by the service interface contract. The skeleton can be generated using annotations automatically by a annotation parser. This avoids human errors and decreases development time as always with automation.

Frameworks like Hibernate, Spring, Axis make heavy use of annotations. When a language needs to be made popular one of the best thing to do is support development of frameworks based on the language. Annotation is a good step towards that and will help grow Java.

When Not to Use Annotations

• Do not over use annotation as it will pollute the code.
• It is better not to try to change the behaviour of objects using annotations. There is sufficient constructs available in oops and annotation is not a better mechanism to deal with it.
• We should not what we are parsing. Do not try to over generalize as it may complicate the underlying code. Code is the real program and annotation is meta.
• Avoid using annotation to specify environment / application / database related information.

Annotation Structure

There are two main components in annotations. First is annotation type and the next is the annotation itself which we use in the code to add meaning. Every annotation belongs to a annotation type.

Annotation Type:

@interface <annotation-type-name> {
method declaration;
}

Annotation type is very similar to an interface with little difference.

• We attach ‘@’ just before interface keyword.
• Methods will not have parameters.
• Methods will not have throws clause.
• Method return types are restricted to primitives, String, Class, enums, annotations, and arrays of the preceding types.
• We can assign a default value to method.

Meta Annotations

Annotations itself is meta information then what is meta annotations? As you have rightly guessed, it is information about annotation. When we annotate a annotation type then it is called meta annotation. For example, we say that this annotation can be used only for methods.

@Target(ElementType.METHOD)
public @interface MethodInfo { }

Annotation Types

1. Documented
   When a annotation type is annotated with @Documented then wherever this annotation is used those elements should be documented using Javadoc tool.
2. Inherited
   This meta annotation denotes that the annotation type can be inherited from super class. When a class is annotated with annotation of type that is annotated with Inherited, then its super class will be queried till a matching annotation is found.
3. Retention
   This meta annotation denotes the level till which this annotation will be carried. When an annotation type is annotated with meta annotation Retention, RetentionPolicy has three possible values:

   @Retention(RetentionPolicy.RUNTIME)
   public @interface Developer {
   	String value();
   }
   

   • Class
     When the annotation value is given as ‘class’ then this annotation will be compiled and included in the class file.
   • Runtime
     The value name itself says, when the retention value is ‘Runtime’ this annotation will be available in JVM at runtime. We can write custom code using reflection package and parse the annotation. I have give an example below.
   • Source
     This annotation will be removed at compile time and will not be available at compiled class.
4. Target
   This meta annotation says that this annotation type is applicable for only the element (ElementType) listed. Possible values for ElementType are, CONSTRUCTOR, FIELD, LOCAL_VARIABLE, METHOD, PACKAGE, PARAMETER, TYPE.

   @Target(ElementType.FIELD)
   public @interface FieldInfo { }
   

Built-in Java Annotations

@Documented, @Inherited, @Retention and @Target are the four available meta annotations that are built-in with Java.

Apart from these meta annotations we have the following annotations.

@Override

When we want to override a method, we can use this annotation to say to the compiler we are overriding an existing method. If the compiler finds that there is no matching method found in super class then generates a warning. This is not mandatory to use @Override when we override a method. But I have seen Eclipse IDE automatically adding this @Override annotation. Though it is not mandatory, it is considered as a best practice.

@Deprecated

When we want to inform the compiler that a method is deprecated we can use this. So, when a method is annotated with @Deprecated and that method is found used in some place, then the compiler generates a warning.

@SuppressWarnings

This is like saying, “I know what I am doing, so please shut up!” We want the compiler not to raise any warnings and then we use this annotation.

Custom Annotations

We can create our own annotations and use it. We need to declare a annotation type and then use the respective annotation is java classes.

Following is an example of custom annotation, where this annotation can be used on any element by giving values. Note that I have used @Documented meta-annotation here to say that this annotation should be parsed by javadoc.

/*
 * Describes the team which wrote the code
 */
@Documented
public @interface Team {
    int    teamId();
    String teamName();
    String teamLead() default "[unassigned]";
    String writeDate();    default "[unimplemented]";
}

Annotation for the Above Example Type

... a java class ...
@Team(
    teamId       = 73,
    teamName = "Rambo Mambo",
    teamLead = "Yo Man",
    writeDate     = "3/1/2012"
)
public static void readCSV(File inputFile) { ... }
... java class continues ...

Marker Annotations

We know what a marker interface is. Marker annotations are similar to marker interfaces, yes they don’t have methods / elements.

/**
 * Code annotated by this team is supreme and need
 * not be unit tested - just for fun!
 */
public @interface SuperTeam { }

... a java class ...
@SuperTeam public static void readCSV(File inputFile) { ... }
... java class continues ...

In the above see how this annotation is used. It will look like one of the modifiers for this method and also note that the parenthesis {} from annotation type is omitted. As there are no elements for this annotation, the parenthesis can be optionally omitted.

Single Value Annotations

There is a chance that an annotation can have only one element. In such a case that element should be named value.

/**
 * Developer
 */
public @interface Developer {
    String value();
}

... a java class ...
@Developer("Popeye")
public static void readCSV(File inputFile) { ... }
... java class continues ...

How to Parse Annotation

We can use reflection package to read annotations. It is useful when we develop tools to automate a certain process based on annotation.

Example:

package com.javapapers.annotations;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
@Retention(RetentionPolicy.RUNTIME)
public @interface Developer {
	String value();
}

package com.javapapers.annotations;
public class BuildHouse {
	@Developer ("Alice")
	public void aliceMethod() {
		System.out.println("This method is written by Alice");
	}
	@Developer ("Popeye")
	public void buildHouse() {
		System.out.println("This method is written by Popeye");
	}
}

package com.javapapers.annotations;
import java.lang.annotation.Annotation;
import java.lang.reflect.Method;
public class TestAnnotation {
	public static void main(String args[]) throws SecurityException,
			ClassNotFoundException {
		for (Method method : Class.forName(
				"com.javapapers.annotations.BuildHouse").getMethods()) {
			// checks if there is annotation present of the given type Developer
			if (method
					.isAnnotationPresent(com.javapapers.annotations.Developer.class)) {
				try {
					// iterates all the annotations available in the method
					for (Annotation anno : method.getDeclaredAnnotations()) {
						System.out.println("Annotation in Method '" + method
								+ "' : " + anno);
						Developer a = method.getAnnotation(Developer.class);
						if ("Popeye".equals(a.value())) {
							System.out.println("Popeye the sailor man! "
									+ method);
						}
					}
				} catch (Throwable ex) {
					ex.printStackTrace();
				}
			}
		}
	}
}

Output:

Annotation in Method 'public void com.javapapers.annotations.BuildHouse.aliceMethod()' : @com.javapapers.annotations.Developer(value=Alice)
Annotation in Method 'public void com.javapapers.annotations.BuildHouse.buildHouse()' : @com.javapapers.annotations.Developer(value=Popeye)
Popeye the sailor man! public void com.javapapers.annotations.BuildHouse.buildHouse()

apt / javac for Annotation Processing

In previous version of JDK apt was introduced as a tool for annotation processing. Later apt was deprecated and the capabilities are included in javac compiler. javax.annotation.processing and javax.lang.model contains the api for processing.

1. java.lang.String
   String class will be the undisputed champion on any day by popularity and none will deny that. This is a final class and used to create / operate immutable string literals. It was available from JDK 1.0
2. java.lang.System
   Usage of System depends on the type of project you work on. You may not be using it in your project but still it is one of the popular java classes around. This is a utility class and cannot be instantiated. Main uses of this class are access to standard input, output, environment variables, etc. Available since JDK 1.0
3. java.lang.Exception
   Throwable is the super class of all Errors and Exceptions. All abnormal conditions that can be handled comes under Exception. NullPointerException is the most popular among all the exceptions. Exception is at top of hierarchy of all such exceptions. Available since JDK 1.0
4. java.util.ArrayList
   An implementation of array data structure. This class implements List interface and is the most popular member or java collections framework. Difference between ArrayList and Vector is one popular topic among the beginners and frequently asked question in java interviews. It was introduced in JDK 1.2
5. java.util.HashMap
   An implementation of a key-value pair data structure. This class implements Map interface. As similar to ArrayList vs Vector, we have HashMap vs Hashtable popular comparisons. This happens to be a popular collection class that acts as a container for property-value pairs and works as a transport agent between multiple layers of an application. It was introduced in JDK 1.2
6. java.lang.Object
   Great grandfather of all java classes. Every java class is a subclass of Object. It will be used often when we work on a platform/framework. It contains the important methods like equals, hashcode, clone, toString, etc. It is available from day one of java (JDK 1.0)
7. java.lang.Thread
   A thread is a single sequence of execution, where multiple thread can co-exist and share resources. We can extend this Thread class and create our own threads. Using Runnable is also another option. Usage of this class depends on the domain of your application. It is not absolutely necessary to build a usual application. It was available from JDK 1.0
8. java.lang.Class
   Class is a direct subclass of Object. There is no constructor in this class and their objects are loaded in JVM by classloaders. Most of us may not have used it directly but I think its an essential class. It is an important class in doing reflection. It is available from JDK 1.0
9. java.util.Date
   This is used to work with date. Sometimes we feel that this class should have added more utility methods and we end up creating those. Every enterprise application we create has a date utility. Introduced in JDK 1.0 and later made huge changes in JDK1.1 by deprecating a whole lot of methods.
10. java.util.Iterator
    This is an interface. It is very popular and came as a replacement for Enumeration. It is a simple to use convenience utility and works in sync with Iterable. It was introduced in JDK 1.2

Did I miss your favourite?

Following are the things in consideration

• When does the event starts (first time) execution – It may be a day / date / time in future.
• Is it a one time event or a recurring event?
• If recurring, what is the periodicity? -
• In recurrence there are two types, like all the events will be on a fixed time which is planned at the time of scheduling. It may be daily / weekly / monthly / yearly / a day of a week / alternate days / only working days.
• Second type is, the recurring event can start after the completion of previous occurrence. There can be a delay between events.
• When does it end, after a constant number of executions or after a time is reached like till Friday only.

So coming up with a nice scheduler api is a quite challenging task. You can consider this as a project for a summer. I know people will jump on and point out numerous existing apis and say why re-invent the wheel? I really hate the jargon re-inventing the wheel, its one of the most misused one. When Google came into market, there were already established players in the field like Yahoo!, Lycos, Ask Jeeves, Alta Vista. But they did a fantastic job and came to top. When you do something of good quality there is always takers for it, do not worry if it is already existing or not. But try to work towards better than the existing.

Considering schedulers in java, we have the wonderful Quartz api. If we want to try something from JDK itself, in util package we have Timer and TimerTask and these were available from JDK 1.3 It is a no-nonsense, sleek and simple to use api. Comparison between this utility and Quartz would be un fair. Quartz supports trillions of possibilities and one of the most used open source schedulers. I have committed plan to write a series of articles on Quartz in future then we can explore it in detail.

java.util.Timer and TimerTask

• Gives facility to schedule a task for future execution in a background thread.
• Task can be scheduled for single or recurring execution.
• In recurrence, consecutive tasks will have regular intervals.
• Timer has got a cancel method using which all the scheduled tasks can be cancelled.
• Timer can be chosen to run as a daemon thread.
• Can be scheduled to start with respect to current time using fixed-delay.
• TimerTask is a thread handle using which we register tasks with the timer.

Important Variations

This api provides two important variations that needs to be noted.

Fixed-delay

Each task execution is scheduled relative to the actual execution time of the previous execution. So what is actual execution? This says that, there is no guarantee that the task will be executed at the pre-planned time and it may be delayed due to garbage collection or some background activity.

We should also not confuse with triggering of task and completion of task. Triggering is the moment at which the Timer fires start a task. If a thread is asked to send email, it may wait for access to the resource like mail server. Only after the email is sent this task is considered to be completed. We need to have this duration in mind when we schedule recurrence tasks. If the recurrence time is shorter and already the previous task is not completed, the subsequent tasks will join the queue.

Fixed-rate

Here each recurring tasks are scheduled relative to the start time of the timer. If there is any delay in execution subsequent executions will occur in quick succession to catch up with the original scheduled time. In previous case, subsequent execution will depend on just previous execution time.

The difference between these two can be easily observed using the below sample program by observing the output.

Sample Java Timer

package com.javapapers.thread;

import java.util.Timer;

public class TimerPiano {

	Timer dingTimer;
	Timer dongTimer;

	public TimerPiano(int ding,int dong) {

		dingTimer = new Timer();
		dingTimer.schedule(new Sound("Ding!"), ding * 1000, ding * 1000);
		//dingTimer.scheduleAtFixedRate(...);

		dongTimer = new Timer();
		dongTimer.schedule(new Sound("Dong!"), dong * 1000, dong * 1000);
		//dongTimer.scheduleAtFixedRate(...);
	}

	public static void main(String args[]) {
		new TimerPiano(2,4);
	}
}

package com.javapapers.thread;

import java.awt.Toolkit;
import java.util.TimerTask;

public class Sound extends TimerTask {

	Toolkit toolkit;
	String sound;

	public Sound(String sound) {
		this.sound = sound;
		//toolkit = Toolkit.getDefaultToolkit();
	}

	public void run() {
		System.out.println(sound);
		//toolkit.beep();
	}
}

• If you want to hear cool sound, un-comment the toolkit line.
• I have not cancelled the tasks and it will keep on running till you force close.
• Replace ‘schedule’ with scheduleAtFixedRate to observe different behaviour.

ScheduledExecutorService is a latest api available from JDK 1.5 onwards and we can see about that in a coming article.

I first learnt DBase III+ and the statement to print is ? "Hello World". Then I went on to to study umpteen number of languages courtesy a poorly planned curriculum. Instead, we should have spent more time on flip-flops.

At the end of this article I have summarized Pascal, C, C++, Lisp, Prolog, Cobol, Basic, Fortran – I studied all these in a 3 year post graduate program and more than that. As I told, I am still not sure of the difference it made. Learning multiple languages is good, but my humble opinion is, do it after spending more time on fundamentals like data structures, algorithms, discrete maths, computer architecture, etc. Okay, where did I left? Lets continue with our System.out.println for now.

What is System.out.println

System.out.println prints the argument passed, into the System.out which is generally stdout.

• System – is a final class and cannot be instantiated. Therefore all its memebers (fields and methods) will be static and we understand that it is an utility class. As per javadoc, “…Among the facilities provided by the System class are standard input, standard output, and error output streams; access to externally defined properties and environment variables; a means of loading files and libraries; and a utility method for quickly copying a portion of an array…”
• out – is a static member field of System class and is of type PrintStream. Its access specifiers are public final. This gets instantiated during startup and gets mapped with standard output console of the host. This stream is open by itself immediately after its instantiation and ready to accept data. When running a program from windows command line, it is the standard console.
• println – println prints the argument passed to the standard console and a newline. There are multiple println methods with different arguments (overloading). Every println makes a call to print method and adds a newline. print calls write() and the story goes on like that.

Change out of System.out.println

‘out’ object can be customized. out gets initialized by java runtime environment at startup and it can be changed by developer during execution. Instead of standard output, in default cases when you run a program through command line, the output is printing in the same command window. We can change that behavior using setOut method as below. In the following example, I have redirected the output to a text file in the same directory.

public class ChangeOut {
	public static void main(String args[]) {
		try {
			System.setOut(new PrintStream(new FileOutputStream("log.txt")));
			System.out.println("Now the output is redirected!");
		} catch(Exception e) {}
	}
}

System.out.println vs loggers like Log4j

Log4J has mulitple levels for logging. If we are writing a real short program, just for experimental/learning purposes SOPs are fine. When we are developing a production quality software project, we should be aware that a professional logger should be used and SOPs should be avoided. Why?

• Flexibility: a professional logger like log4j provides different levels for logging. We can seggregate the log message accordingly. For example, X messages should be printed only on PRODUCTION, Y messages should be printed on ERROR, etc.
• Configurability: in just one parameter change we can switch off all the logging statements.
• Maintainability: imagine if we have hundreds of SOPs littered all through the application, it would be difficult to maintain the program over a period.
• Granularity: In an application, every single class can have a different logger and controlled accordingly.
• Utility: Option for redirecting the message is limited in System.out, but in case of a logger you have appenders which provides numerous options. We can even create a custom ouput option and redirect it to that.

Having said all the above, we still use System.out.println for logging and debugging. Which should be strictly avoided. This is driven by (bad)habit. I want to share how a habit became a convention. In this case its a good habit. Its using ‘i’, ‘j’ as index in for-loop. In FORTRAN language, we need not declare integer variables. Variable names that start with i, j, k, l, m and n are integer variables. So, FORTRAN developers named for-loop index with i,j,k and that habit carried on to other languages. Just a habit and became a good convention!

System.out.println and Performance

There is a general notion that SOPs are bad in performance. When we analyze deeply, the sequence of calls are like println -> print -> write() + newLine(). This sequence flow is an implementation of Sun/Oracle JDK. Both write() and newLine() contains a synchronized block. Synchronization has a little overhead, but more than that the cost of adding characters to the buffer and printing is high.

When we run a performance analysis, run multiple number of SOP and record the time, the execution duration increases proportionally. Performance degrades when we print more that 50 characters and print more than 50,000 lines.

It all depends on the scenario we use it. Whatever may be the case, do not use System.out.println for logging to stdout.

Static Import to Shorten SOP

Someone complained that System.out.println is a loooong statement to print something. static import may shorten it a bit but it is not recommended, because it results in poor readability. I am just using this situation to explain static import and avoid using it in the below scenario.

import static java.lang.System.out;

public class ShortSOP {
public static void main(String[] args) {
out.println("Hello, world");
}
}

In Eclipse you have programmed shortcuts like ctrl + spac to help you out.

System.err and System.in

As a related section, I wish to discuss about ‘err’ and ‘in’. ‘in’ is associated with InputStream. Opposite to ‘out’, ‘in’ is used to get input from standard console generally keyboard.
‘err’ is associated with PrintStream and prints the argument to the standard error output stream. When you use eclipse kind of IDE you can see the differene in ouput between ‘out’ and ‘err’.

public class InOutErr {
public static void main(String args[]) {
try {

BufferedReader reader = new BufferedReader(System.in);
String filename = reader.readLine();

  InputStream input = new FileInputStream(filename);
  System.out.println("File opened...");

} catch (IOException e){
  System.err.println("Where is that file?");
}
}
}

Print in other languages

DBASE III+
? "Hello World"

C

 #include <stdio.h>
 #include <stdlib.h>

 int main(void)
 {
  printf("Hello, world");
  return EXIT_SUCCESS;
 }

CPP

 #include <iostream>

 int main()
 {
 	std::cout << "Hello, World." << std::endl;
 }

BASIC

10 PRINT "HELLO WORLD"

FORTRAN

 PROGRAM HELLOWORLD
 10 FORMAT (1X,11HHELLO WORLD)
 WRITE(6,10)
 END

COBOL

 IDENTIFICATION DIVISION.
 PROGRAM-ID. Hello.
 ENVIRONMENT DIVISION.
 DATA DIVISION.
 PROCEDURE DIVISION.
	Display 'Hello, World'.
	STOP RUN.

LISP

	(DEFUN HELLO-WORLD ()
	(PRINT (LIST 'HELLO 'WORLD)))

PROLOG

go :-
	writeln('Hello World').

Yes, I sourced all this programs from Internet :-) How come you expect me to remember all these! System.out.println(“Bye”);

• In other words, we want to have separate instances(private copy) of a class so that there will not be any conflict among multiple threads. Each instance will be unique for each thread. This is nothing but a way of implementing threadsafety.
• An important point about ThreadLocal variable is the global access. It can be accessed from anywhere inside the thread. Also note that, it is declared static and final.

What is threadsafe?

A thread is a single line of process. When we refer multi-threaded applications, we mean that there mulitple (sequential flow of control) line of process that runs through the same lines of code. In such situation, there is a possibility of one sequence(thread) accessing/modifying data of other sequence(thread). When data cannot be shared like this, then we make it threadsafe. Following are the some of the different ways of implementing threadsafe operation:

• Re-entrancy
• Mutual exclusion (synchronization)
• Thread-local
• Atomic operation

So, in the above list Thread-local is one option. Hope now we get how ThreadLocal fits in the cube.

Uses of ThreadLocal

I cannot resist but quote Joshua Bloch (who better I can choose for this section),
in his own words:

• Genuine per-thread context, such as user id or transaction id. Works great. Easy to clean up when the thread exits the scope. No leaks.
• Per-thread instances for performance.
• “Sleazing” values through callbacks that you don’t control: sometimes you must call a library method that calls back into your package. At this point, you need some context that you were unable to pass to yourself, due to deficiencies in the library. In this rare situation, thread locals can be a lifesaver.

Above points, in my own terms: We have an object that is not threadsafe and we want to use it safely. We go for synchronization by enclosing that object in synchronized block. Other way around is using ThreadSafe, what it does is holds separate instance for each thread and makes it safe.

Example for ThreadLocal

package com.javapapers;

import java.text.SimpleDateFormat;
import java.util.Date;

public class ThreadLocalExample {
	private static final ThreadLocal<SimpleDateFormat> formatter = new ThreadLocal<SimpleDateFormat>() {

		protected SimpleDateFormat initialValue() {
			return new SimpleDateFormat("yyyyMMdd HHmm");
		}
	};

	public String formatIt(Date date) {
		return formatter.get().format(date);
	}
}

In the above sample code, get() method is key to understanding. It returns the value in the current thread’s copy of this thread-local variable. If the variable has no value for the current thread, it is first initialized to the value returned by an invocation of the initialValue method.

Example from javadoc

The class below generates unique identifiers local to each thread. A thread’s id is assigned the first time it invokes ThreadId.get() and remains unchanged on subsequent calls.

 import java.util.concurrent.atomic.AtomicInteger;

 public class ThreadId {
     // Atomic integer containing the next thread ID to be assigned
     private static final AtomicInteger nextId = new AtomicInteger(0);

     // Thread local variable containing each thread's ID
     private static final ThreadLocal<Integer> threadId =
         new ThreadLocal<Integer>() {
             @Override protected Integer initialValue() {
                 return nextId.getAndIncrement();
         }
     };

     // Returns the current thread's unique ID, assigning it if necessary
     public static int get() {
         return threadId.get();
     }
 }

Use of ThreadLocal in Java API

In JDK 1.7 we have got a new class namely ThreadLocalRandom. It can be used to generate random numbers specific to parallel threads. Seed for random number will be unique for each thread. This is a real cool utility.

Following is the code that implements ThreadLocal in the above class:

    private static final ThreadLocal<ThreadLocalRandom> localRandom =
        new ThreadLocal<ThreadLocalRandom>() {
            protected ThreadLocalRandom initialValue() {
                return new ThreadLocalRandom();
            }
    };

Example using ThreadLocalRandom

package com.javapapers;

import java.util.concurrent.ThreadLocalRandom;

public class ThreadLocalRandomExample {

	public static void main(String args[]) throws InterruptedException {

		//tossing 3 coins
		for (int i = 0; i < 3; i++) {
			final Thread thread = new Thread() {

				public void run() {
					System.out.print(Thread.currentThread().getName() + ":");

					// generating 3 random numbers - random for every thread
					for (int j = 0; j < 3; j++) {
						final int random = ThreadLocalRandom.current().nextInt(
								1, 3);
						System.out.print(random + ",");
					}
					System.out.println();
				}
			};
			thread.start();
			thread.join();
		}
	}
}

ThreadLocal and Memory Leaks

ThreadLocal is not evil, it is a nice utility API. It all depends on how we use it. We should learn to choose the right tool for the right situation. We cannot use cannons to burst mosquitoes, but do not blame the cannons.

There are strong complaints all over the web saying ThreadLocals will cause memory leaks. ‘Mostly’ No!

I wish to quote Joshua Bloch,

“…There is nothing inherently wrong with thread locals: They do not cause memory leaks. They are not slow. They are more local than their non-thread-local counterparts (i.e., they have better information hiding properties). They can be misused, of course, but so can most other programming tools….”

Why ‘Mostly’ No? – In case of ‘self-referential structures’, there is a memory leak. Refer the bug_id 6254531

It is a nice utility for collections. Every collection is unique on its own and imagine if we have have to write logic on our own for every collection when there is a need to iterate it. Instead, java forces a collection to deliver an iterator.

These nice utilities makes java lovable, isn’t it?

Important points to note:

• We can iterate only in one direction
• Iteration can be done only once. If you reach the end of series its done. If we need to iterate again we should get a new Iterator.

Iterator Example without Generics

package com.javapapers;

import java.util.ArrayList;
import java.util.Iterator;

public class ExampleIterator {

	public static void main(String args[]){
		ArrayList animal = new ArrayList();
		animal.add("Horse");
		animal.add("Lion");
		animal.add("Tiger");

		Iterator animalItr = animal.iterator();

		while(animalItr.hasNext()) {
			String animalObj = (String)animalItr.next();
			System.out.println(animalObj);
		}
	}

}

Without generics, Iterator returns the Object and we need to typecast it.

Iterator Example using Generics

package com.javapapers;

import java.util.ArrayList;

public class ExampleIterator {

	public static void main(String args[]){
		ArrayList<String> animal = new ArrayList<String>();
		animal.add("Horse");
		animal.add("Lion");
		animal.add("Tiger");

		for(String animalObj : animal) {
			System.out.println(animalObj);
		}
	}

}

Output:
Horse
Lion
Tiger

Look how simple it is. There is no reference to the Iterator explicitly since we are using for-each of generics.

Iterable and Iterator

To make an object iterable it needs to emit an Iterator object. To enforce this contract, Iterator interface is to be used. It contains a method named iterator() and it returns Iterator. Hence, any class that implements Iterable will return an Iterator.

public interface Collection<E> extends Iterable<E> {

For example take any Collection. A Collection is an interface that represents container for series of elements. Every collections like ArrayList, Vector implements Collection and so Iterator.

• One advantage of Iterable is, when you implement Iterable then those object gets support for for:each loop syntax.

Removing elements using Iterator

• Iterator has a remove method using which we can delete elements from the underlying object.
• It removes the last element returned by the iterator.

Difference between Iterator and Enumeration interfaces

1. remove() method is introduced in iterator. Using this method we can remove element from the underlying collection which we are iterating.
2. Enumeration has two methods and both are available in iterator. Method names for both of them are shortened.

ListIterator an even better Iterator for a List containing more utility methods like getting index of elements and adding elements to the base object. Using ListIterator we can iterate in both the directions.

ConcurrentModificationException

Look at the following code, it throws ConcurrentModificationException. We cannot add or remove elements to the underlying collection when we are using an iterator.

package com.javapapers;

import java.util.ArrayList;

public class ExampleIterator {

	public static void main(String args[]){
		ArrayList<String> animal = new ArrayList<String>();
		animal.add("Horse");
		animal.add("Lion");
		animal.add("Tiger");

		for(String animalObj : animal) {
			System.out.println(animalObj);
			animal.add("Hyena");
		}
	}
}

Output:
Horse
Exception in thread "main" java.util.ConcurrentModificationException
	at java.util.ArrayList$Itr.checkForComodification(Unknown Source)
	at java.util.ArrayList$Itr.next(Unknown Source)
	at com.javapapers.ExampleIterator.main(ExampleIterator.java:13)

Implementing our own Custom Iterator

We will create our own custom class and make it implement Iterable, so that it returns an Iterator using which we can iterate the elements.

package com.javapapers;

import java.util.ArrayList;
import java.util.Iterator;

public class AnimalIterator<String> implements Iterator<Object> {

	private ArrayList<?> animal;
	private int position;

	public AnimalIterator(Animal animalBase) {
		this.animal = animalBase.getAnimal();
	}

	@Override
	public boolean hasNext() {
		if (position < animal.size())
			return true;
		else
			return false;
	}

	@Override
	public Object next() {
		Object aniObj = animal.get(position);
		position++;
		return aniObj;
	}

	@Override
	public void remove() {
		animal.remove(position);
	}

}

package com.javapapers;

import java.util.ArrayList;
import java.util.Iterator;

public class Animal implements Iterable<String> {

	private ArrayList<String> animal = new ArrayList<String>();

	public Animal(ArrayList animal){
		this.animal = animal;
	}

	public ArrayList getAnimal() {
		return animal;
	}

	@Override
	public Iterator<String> iterator() {
		return new AnimalIterator(this);
	}

}

package com.javapapers;

import java.util.ArrayList;

public class TestIterator {

	public static void main(String args[]) {
		ArrayList<String> animalList = new ArrayList();
		animalList.add("Horse");
		animalList.add("Lion");
		animalList.add("Tiger");
		Animal animal = new Animal(animalList);
		for (String animalObj : animal) {
			System.out.println(animalObj);
		}
	}
}

Output:
Horse
Lion
Tiger