My previous three blogs have focused on the following areas in the Android platform:

• A Hello World Application
• A Basic Calculator Application
• A Sneak Peek at Layouts

This blog post is going to focus on Andriod application integration with the outside world using RESTful web services. Also it is going to look at how the wonderful Google Maps product can be integrated within Android App. My technology configuration as stated in the first blog post remains unchanged.

Today’s tutorial is going to do two things. One, it is going to communicate with a public RESTful web service API, supply a postal code and getting details of possible matches for the code. The possible matches will be listed for the user’s convenience. On selecting one of the matches, the Google Map within the page will zoom in on the location.

To implement this I need to create two activities. The first activity PostalCodeSearchActivity will prompt the end user to supply the postal code/zip code to search. On receiving the postal code, the PostalCodeSearchActivity activates the second Activity RESTfulWebServicesActivity. As a part of RESTfulWebServicesActivity’s creation process, it starts an asynchronous task which interrogates the public RESTful Web Service API and retrieves possible matches. These are displayed in the RESTfulWebServicesActivity. On selection of a location, the location is displayed in the Google Maps view of the application. Enough of theory, let’s first look at the PostalCodeSearchActivity code.

package com.android.rest;

import android.app.Activity;
import android.content.Intent;
import android.graphics.Typeface;
import android.os.Bundle;
import android.text.InputType;
import android.view.Gravity;
import android.view.View;
import android.view.View.OnClickListener;
import android.widget.Button;
import android.widget.EditText;
import android.widget.LinearLayout;
import android.widget.TextView;
import android.widget.LinearLayout.LayoutParams;

public class PostalCodeSearchActivity extends Activity {
	
	@Override
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        
        LinearLayout layout = new LinearLayout(this);
        layout.setOrientation(LinearLayout.VERTICAL);
        
        LinearLayout.LayoutParams params = new LinearLayout.LayoutParams(LayoutParams.FILL_PARENT, 
        		LayoutParams.FILL_PARENT);
        layout.setLayoutParams(params);
        
		TextView label = new TextView(this);
		label.setText("Enter the zip code");
		label.setMaxHeight(100);
		label.setTypeface(Typeface.DEFAULT, Typeface.BOLD);
		label.setGravity(Gravity.CENTER);
		label.setTextColor(this.getResources().getColor(R.color.white));

		final EditText searchField = new EditText(this);
		searchField.setInputType(InputType.TYPE_NUMBER_VARIATION_NORMAL);
		searchField.setMaxHeight(100);
		searchField.setTypeface(Typeface.DEFAULT, Typeface.BOLD);
		searchField.setGravity(Gravity.LEFT);
		searchField.setTextColor(this.getResources().getColor(R.color.white));
		searchField.requestFocus();

		Button searchButton = new Button(this);
		searchButton.setText("Search");
		searchButton.setOnClickListener(new OnClickListener() {
			
			@Override
			public void onClick(View v) {
				Intent i = new Intent(PostalCodeSearchActivity.this, RESTfulWebServicesActivity.class);
				i.putExtra(PostalCodeSearchActivity.this.getString(R.string.zip), searchField.getText().toString());
				startActivity(i);
			}
		});
		
		layout.addView(label);
		layout.addView(searchField);
		layout.addView(searchButton);
		
		this.setContentView(layout);         
    }
}

In the PostalCodeSearchActivity’s onCreate method, a content View for postal code / zip code search is created. It consists of a EditText control to accept user input and a search button to trigger the postal code search. Refer lines 47 to 55 for implementation of the search button’s onClickListener. The onclickListener requires implementation of onClick method. As per our design, we need to pass on the user provided zip code information to RESTfulWebServicesActivity. In Android, this is implemented via the Intent class. We create an intent using two parameters, the first is the Context which is PostalCodeSearchActivity instance and second is the Activity class to instantiate RESTfulWebServicesActivity; refer line 51. Using putExtra method of the Intent we pass on the user inputted postal code information. The RESTfulWebServicesActivity activity is initiated by invoking the startActivity method with the Intent instance as its argument. Note the layout information dynamically defined in the PostalCodeSearchActivity class could have been easily defined in a xml. I did it out of habit but the best practice is to use a xml to define the PostalCodeSearchActivity layout.

Now let’s look at RESTfulWebServicesActivity’s source code. Here I have adhered to the best practice with the page content layout been defined in xml. Refer the main.xml located within res/layout folder of the Andriod project.

<?xml version="1.0" encoding="utf-8"?>
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:id="@+id/main"
    android:layout_width="fill_parent"
    android:layout_height="fill_parent"
    android:orientation="vertical" >

    <com.google.android.maps.MapView
        android:id="@+id/map"
        android:layout_width="300dp" 
        android:layout_height="250dp"
        android:layout_gravity="center"
        android:enabled="true"
        android:clickable="true"
        android:apiKey="AABBCCXX"
     />
    <ListView
        android:id="@+id/list"
        android:layout_width="wrap_content" 
        android:layout_height="wrap_content"
     />
    
    <Button 
    	android:id="@+id/backButton"
    	android:text="Go back to Search Page"
    	android:layout_gravity="center"
    	android:layout_width="wrap_content"
    	android:layout_height="wrap_content"
    />
</LinearLayout>

In the main.xml, we have defined the following elements an instance of MapView named map, a ListView named list and Button named backButton.

The MapView is a ready-to-use component for Google Maps. This component will display the location for given zip code/postal code. The MapView will only work once the developer obtains a free license. Google provides key string which is stored in the apiKey attribute of MapView. Details for obtaining the key are provided here. The ListView will display all possible matches for a given zip code and the back button will navigate back to the PostalCodeSearchActivity in case the user intends to revisit the zip code value. Next let’s look at the RESTfulWebServicesActivity source code.

package com.android.rest;

import com.android.async.GeoNamesAsyncTask;
import com.google.android.maps.MapActivity;
import com.google.android.maps.MapController;
import com.google.android.maps.MapView;

import android.content.Intent;
import android.os.Bundle;
import android.view.View;
import android.view.View.OnClickListener;
import android.widget.Button;

public class RESTfulWebServicesActivity extends MapActivity {
    
	/** Called when the activity is first created. */
    @Override
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        this.setContentView(R.layout.main);
        
        //Reset MapView
        MapView map = (MapView)this.findViewById(R.id.map);
        MapController control = map.getController();
        control.setZoom(2);
        
        //Add dynamic behaviour to Back button
        Button backButton = (Button)this.findViewById(R.id.backButton);
        backButton.setOnClickListener(new OnClickListener() {
			
			@Override
			public void onClick(View v) {
				finish();
			}
		});
        
        //Retrieve matching locations
        GeoNamesAsyncTask task = new GeoNamesAsyncTask(this);
        Intent i = this.getIntent();
        String zipCode = i.getStringExtra(this.getString(R.string.zip));
        
        if (zipCode == null) {
        	zipCode = "24501";
        }
        
        task.execute(zipCode);
                
    }

	@Override
	protected boolean isRouteDisplayed() {
		return false;
	}
}

Note that the Activity extends MapActivity. This is extremely important. This allows MapView to be used in the context of RESTfulWebServicesActivity class. In the onCreate method of the Activity, the content view is set to main.xml. The MapView is reset via lines 23 to 25. This is necessary or the MapView tends to retain the last selected result. Once a user has selected a zip code, the appropriate location is highlighted in the MapView; even if user navigates back to the PostalCodeSearchActivity and returns to the RESTfulWebServicesActivity, the previously selected location is displayed. Therefore we find the MapView component via the findViewById method, gain access to the view’s MapController and zoom out to move out of focus of the location. Next we implement a OnClickListener to the backButton. The onClick method implementation simply invokes finish method of the Activity. This causes the control to return back to PostalCodeSearchActivity.

As discussed earlier, the PostalCodeSearchActivity has supplied user input zip code to RESTfulWebServicesActivity. We create a asynchronous task named GeoNamesAsyncTask. Here’s the source code of GeoNamesAsyncTask.

package com.android.async;

import java.util.List;

import com.android.rest.R;
import com.android.rest.adapter.PostalCodeAdapter;
import com.android.rest.vo.GeoName;
import com.google.android.maps.MapActivity;

import android.content.Context;
import android.os.AsyncTask;
import android.view.View;
import android.view.ViewGroup;
import android.widget.LinearLayout;
import android.widget.ListView;
import android.widget.LinearLayout.LayoutParams;

public class GeoNamesAsyncTask extends AsyncTask<String, Void, List<GeoName>> {

	private Context ctx = null;
	
	public GeoNamesAsyncTask(Context ctx) {
		this.ctx = ctx;
	}
	
	@Override
	protected List<GeoName> doInBackground(String... arg0) {
		return new GeoNamesService().searchPostalCode(arg0[0]);
	}

	@Override
	protected void onPostExecute(List<GeoName> result) {
		this.populateActivity(result);
	}
	
	void populateActivity(List<GeoName> locations) {
		
		//Associate Adapter to ListView for matching locations
		MapActivity mapAct = (MapActivity)ctx;
		ListView list = (ListView) mapAct.findViewById(R.id.list);

		PostalCodeAdapter adapter = new PostalCodeAdapter(this.ctx, locations);
		list.setAdapter(adapter);
				
	}
}	

The asynchronous behavior is induced in GeoNamesAsyncTask by making AsyncTask as its parent class. The AsyncTask accepts three parameters as its formal type parameters. The first parameter defines the type of argument it will accept in its execute and doInBackground methods. The third parameter defines the type for the onPostExecute method. The asynchronous task is triggered in RESTfulWebServicesActivity by invoking the execute method, refer line 46.

The GeoNamesAsyncTask constructor accepts a Context as argument. This is to retain reference to the triggering Activity. Within the task we need to implement two methods doInBackground and onPostExecute method.

The doInBackground method is activated on execution of the execute method. The GeoNamesAsyncTask in turn uses the services of GeoNamesService class to invoke relevant RESTful web service APIs and get matching location information. Details of GeoNamesService will be covered later.

Once the information is retrieved, the task’s onPostExecute method is invoked. Here we invoke custom populateActivity method which populates the ListView of RESTfulWebServicesActivity with matching location information.

Why does the RESTful Web Services processing needs to be asynchoronous? In case you try to do it in the context of the parent thread, the following exception is thrown:

12-21 17:38:38.058: E/AndroidRuntime(638): Caused by: android.os.NetworkOnMainThreadException

Now let’s look GeoNamesService source code.

package com.android.async;

import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.util.List;

import org.apache.http.HttpEntity;
import org.apache.http.HttpResponse;
import org.apache.http.client.ClientProtocolException;
import org.apache.http.client.HttpClient;
import org.apache.http.client.methods.HttpGet;
import org.apache.http.impl.client.DefaultHttpClient;

import com.android.rest.vo.GeoName;
import com.google.gson.Gson;

public class GeoNamesService {

	private static final String GEONAME_RESTURL 
		= "http://api.geonames.org/postalCodeSearchJSON?maxRows=4&username=demo&postalcode=";
	
	GeoNamesService() {
		
	}
	
	public List<GeoName> searchPostalCode (String code) {
		
		String url = GEONAME_RESTURL + code ;
		HttpClient client = new DefaultHttpClient();
		HttpGet httpGet = new HttpGet(url);
		try {
			HttpResponse response = client.execute(httpGet);
			HttpEntity entity = response.getEntity();
			
			if(entity != null) {
				InputStream stream = entity.getContent();
				String responseString = convertStreamToString(stream);
				
				DataWrapper wrap = new DataWrapper();
				wrap = wrap.fromJson(responseString);
				return wrap.postalCodes;
			}
			
		} catch (ClientProtocolException e) {
			e.printStackTrace();
		} catch (IOException e) {
			e.printStackTrace();
		}
		
		return null;
	}
	
	private static String convertStreamToString(InputStream is) {
		BufferedReader reader = new BufferedReader(new InputStreamReader(is));
        StringBuilder sb = new StringBuilder();
 
        String line = null;
        try {
            while ((line = reader.readLine()) != null) {
                sb.append(line + "\n");
            }
        } catch (IOException e) {
            e.printStackTrace();
        } finally {
            try {
                is.close();
            } catch (IOException e) {
                e.printStackTrace();
            }
        }
        return sb.toString();
	}
	
	public class DataWrapper {
		public List<GeoName> postalCodes = null;
		
		public DataWrapper fromJson(String jsonString) {
			return new Gson().fromJson(jsonString, DataWrapper.class);
		}
	}		
}

The RESTful Web Service API I am invoking belongs to geonames.org. The site provides free geographical database services. The registration is free and useful as the demo user has quota limits which routinely gets exceeded. I am using an API which provides me JSON payload. To convert JSON to Java Object I am using the Gson project. In case you need a framework for XML binding have a look at Simple.

The implementation of searchPostalCode method uses Apache Commons HTTPClient project to establish a HTTP connection with the Web Service. The Json response string is unmarshalled into Java object using Gson. Here’s the JSON string for postal code 80907:

{"postalCodes":[{"adminName2":"El Paso","adminCode2":"041","adminCode1":"CO","postalCode":"80907","countryCode":"US","lng":-104.817034,"placeName":"Colorado Springs","lat":38.876001,"adminName1":"Colorado"}]}

Here’s the structure of the GeoName class. The DataWrapper is part of GeoNamesService. The top level element in the JSON string is postalCodes which matches the attribute name in the DataWrapper class. The rest of the data maps to the List.

package com.android.rest.vo;

public class GeoName {
	
	public int postalCode = 0;
	public String placeName = null;
	public String countryCode = null;
	public float lat = 0.0f;
	public float lng = 0.0f;
}

The GeoName class defines only the relevant attributes from the JSON response. The attribute name within the JSON string and the GeoName class attributes are an exact match.

The final piece of the puzzle is the populateActivity method of GeoNamesAsyncTask. The method associates the List to the ListView using the PostalCodeAdapter. Here’s the source code of PostalCodeAdapter.

package com.android.rest.adapter;

import java.util.ArrayList;
import java.util.List;

import com.android.rest.OverlayItems;
import com.android.rest.R;
import com.android.rest.vo.GeoName;
import com.google.android.maps.GeoPoint;
import com.google.android.maps.MapActivity;
import com.google.android.maps.MapController;
import com.google.android.maps.MapView;
import com.google.android.maps.Overlay;
import com.google.android.maps.OverlayItem;

import android.app.AlertDialog;
import android.content.Context;
import android.content.DialogInterface;
import android.graphics.Typeface;
import android.view.Gravity;
import android.view.View;
import android.view.View.OnClickListener;
import android.view.ViewGroup;
import android.widget.AbsListView;
import android.widget.BaseAdapter;
import android.widget.LinearLayout;
import android.widget.LinearLayout.LayoutParams;
import android.widget.TextView;

public class PostalCodeAdapter extends BaseAdapter {

	private Context ctx = null;
	
	private List<GeoName> names = new ArrayList<GeoName>();

	public PostalCodeAdapter(Context ctx, List<GeoName> locations) {
		this.ctx = ctx;
		this.names = locations;
	}
	
	
	@Override
	public int getCount() {		
		return names.size();
	}

	@Override
	public Object getItem(int arg0) {
		return null;
	}

	@Override
	public long getItemId(int arg0) {
		return 0;
	}

	@Override
	public View getView(int arg0, View arg1, ViewGroup arg2) {

		LinearLayout layout = new LinearLayout(ctx);
		AbsListView.LayoutParams params = new AbsListView.LayoutParams(LayoutParams.FILL_PARENT, 
				LayoutParams.FILL_PARENT);
		layout.setLayoutParams(params);
		
		layout.setOrientation(LinearLayout.HORIZONTAL);
		
		GeoName location = this.names.get(arg0);
				
		TextView value = new TextView(this.ctx);
		value.setText(location.placeName);
		value.setMaxHeight(100);
		value.setTypeface(Typeface.DEFAULT, Typeface.NORMAL);
		value.setGravity(Gravity.CENTER);
		value.setTextColor(this.ctx.getResources().getColor(R.color.white));
		value.setOnClickListener(new CityClickListener(location));
		
		layout.addView(value);
		
		return layout;
	}
	
	class CityClickListener implements OnClickListener {

		private GeoName geoName = null;
		
		CityClickListener(GeoName name) {
			this.geoName = name;
		}
		
		@Override
		public void onClick(View v) {
		
			AlertDialog.Builder builder = new AlertDialog.Builder(ctx);
			builder.setView(createView());
			builder.setTitle("Details of " + geoName.placeName);
		    builder.setCancelable(true);

			builder.setPositiveButton("OK", new DialogInterface.OnClickListener() {
		           public void onClick(DialogInterface dialog, int id) {
		        	   dialog.cancel();
		           }
			});
			
			AlertDialog alert = builder.create();
			alert.show();
			
			updateMap(); 
			
		}
		
		private void updateMap() {
			
			MapActivity mapAct = (MapActivity)ctx;
			MapView map = (MapView)mapAct.findViewById(R.id.map);
			map.setScrollBarStyle(MapView.SCROLLBARS_INSIDE_INSET);
			map.setBuiltInZoomControls(Boolean.TRUE);
			map.displayZoomControls(Boolean.TRUE);
			
			GeoPoint point = new GeoPoint((int)(geoName.lat * 1E6), (int)(geoName.lng * 1E6));
			MapController mc = map.getController();
			mc.setZoom(17);
			mc.setCenter(point);
			mc.animateTo(point);
			
			List<Overlay> overlays = map.getOverlays();
			overlays.clear();

			OverlayItems items = new OverlayItems(ctx.getResources().getDrawable(R.drawable.marker));
			OverlayItem item = new OverlayItem(point, geoName.placeName, "" + geoName.postalCode);
			
			items.addOverlay(item);
			overlays.add(items);
			
						
		}
		
		
		private View createView() {
			
			LinearLayout l = new LinearLayout(ctx);
			l.setOrientation(LinearLayout.VERTICAL);
			LinearLayout.LayoutParams params = new LayoutParams(100, 300);
			l.setLayoutParams(params);
			
			TextView city = new TextView(ctx);
			city.setText("City, Country : " + geoName.placeName + ", " + geoName.countryCode);
			city.setMaxHeight(100);
			city.setTypeface(Typeface.DEFAULT, Typeface.NORMAL);
			city.setGravity(Gravity.CENTER);
			city.setTextColor(ctx.getResources().getColor(R.color.white));

			TextView orientation = new TextView(ctx);
			orientation.setText("Orientation : " + geoName.lat + " || " + geoName.lng);
			orientation.setMaxHeight(100);
			orientation.setTypeface(Typeface.DEFAULT, Typeface.NORMAL);
			orientation.setGravity(Gravity.CENTER);
			orientation.setTextColor(ctx.getResources().getColor(R.color.white));
						
			l.addView(city);
			l.addView(orientation);
			
			return l;
		}	
	}
}

Refer the getView method on line number 61. Note the use of AbsListView.LayoutParams instead of LinearLayout.LayoutParams. If LinearLayout.LayoutParams is used the following exception is thrown:

java.lang.ClassCastException: android.widget.LinearLayout$LayoutParams cannot be cast to android.widget.AbsListView$LayoutParams

For clarification of why this occurs refer here.

The CityClickListener displays a dialog window with city, country and latitude and longitude details. The method createView creates the dialog window contents. The updateMap method updates the map with selected location’s lat/lng details. This is done by instantiating a GeoPoint. The GeoPoint accepts integer values for latitude and longitude in microdegrees; therefore the lat/lng values of GeoName has to multipled by 1E6 to get value in microdegrees. Next we set the zoom value of the MapView’s MapController and use the center and animateTo method to assign the GeoPoint.

To get the pointer effect of Google Maps, we add an OverLay to the Map, refer line number 125 to 132.

Here’s the output of our effort.

In case your resume showcases experience in using XML, the interviewer would normally probe you regarding what selection criteria do you apply in modeling a data member as a XML element or attribute.

The following are some of the selection criteria which I could think of or gather from internet:

Readability

At the end of the day, XML is human readable, hence some effort must be expended in keeping format easy to read. For example consider the following two XMLs PersonElements and PersonElements_Attributes.

<?xml version="1.0" encoding="UTF-8"?>
<!-- PersonElements.xml -->
<Person>
	<FirstName>Steve</FirstName>
	<MiddleName>M</MiddleName>
	<LastName>Richardson</LastName>
	<DateOfBirth>10-March-1988</DateOfBirth>
	<Gender>Male</Gender>
	<UniqueIdentifierNumber>123-45-6789</UniqueIdentifierNumber>
</Person>

<?xml version="1.0" encoding="UTF-8"?>
<!-- PersonElements_Attributes.xml -->
<Person uniqueIdentifierNumber="123-45-6789" gender="male">
	<FirstName>Steve</FirstName>
	<MiddleName>M</MiddleName>
	<LastName>Richardson</LastName>
	<DateOfBirth>10-March-1988</DateOfBirth>
</Person>

In PersonElements.xml, all data members have been modeled as elements; in PersonElements_Attributes.xml, some data members namely uniqueIdentifierNumber and gender have been modeled as attributes. Both XMLs represent the same data but in different formats. For a human readability standpoint PersonElements is easier to read vis-a-vis PersonElements_Attributes.

Data or meta-data

The second criteria I would apply is to verify if the data member represents data with respect to the parent element or metadata. Consider the following XML metadata.xml.

<?xml version="1.0" encoding="UTF-8"?>
<Person id="1AEFHG234">
	<FirstName>Steve</FirstName>
	<MiddleName>M</MiddleName>
	<LastName>Richardson</LastName>
	<DateOfBirth>10-March-1988</DateOfBirth>
	<Gender tc="1">Male</Gender>
	<UniqueIdentifierNumber tc="0">123-45-6789</UniqueIdentifierNumber>
	<AnnualIncome currency="USD" currencycode="1">120000</AnnualIncome>
</Person>

The XML format has become a data communication format of choice for electronic communication e.g. web services. Therefore information pertinent for system processing needs to be incorporated within the XML message payload. This additional information may not have a strong relationship or belongingness with the containing element, however is important from a system processing standpoint. Such information can be modeled as an attribute. In our example, the id attribute uniquely identifies the Person element. The id attribute by itself does not have any business context significance with the Person element but purely present from B2B processing standpoint.

Secondly we have introduced the attribute tc for two elements namely Gender and UniqueIdentifierNumber. From a human readability perspective, the actual values of these elements are sufficient, but from system processing point of view, getting codes instead of description is preferred, hence we have the tc or typecode attribute which points to code value 1. In the second case ‘UniqueIdentifierNumber’ from the formatting a human may decipher that the unique number is US Social Security Number but for the convenience of system processing we use tc=”1″ attribute to identify that this is a social security number. This technique is commonly used in ACORD(An insurance domain specific XML standard) XML modeling.

The third and the final example is that of AnnualIncome element. Here we need to model two aspects, measurement unit and value. Containing them together in one element is achieved by keeping the currency code or description as attribute and measurement value ’120000′ as the element value. alternative methods for modeling would have been as follows:

<!-- Option 1 -->
<Person>
.
.
.
	<AnnualIncomeCurrencyCode>USD</AnnualIncomeCurrencyCode>
	<AnnualIncome>120000</AnnualIncome>
.
.
</Person>

<!-- Option 2 -->
<Person>
.
.
.
	<CurrencyCode>USD</CurrencyCode>
	<AnnualIncome>120000</AnnualIncome>
.
.
</Person>

<!-- Option 3 -->
<Person>
.
.
.
	<AnnualIncome>
		<CurrencyCode>USD</CurrencyCode>
		<Value>120000</Value>
	</AnnualIncome>
.
.
</Person>

Consider an XML containing a lot of measures and measure types; it would become difficult to comprehend if any of the three above mentioned approaches are used.

Extensibility

XML used for electronic communication needs to be flexible for accepting change. Inevitably business requirements change, data structures evolve; a data member modeled as an attribute cannot be extended further. For example, consider the XML Extension-1.xml. It does not provide any room for the publisher attribute to evolve.

<!-- Extension-1.xml -->
<Books>
	<Book id="12345" publisher="McGraw Hill">
		<Title>XML Modeling - An approach</Title>
		<Author>Ray Johnson</Author>
		<BookReleaseDate>20-March-2001</BookReleaseDate>
	</Book>
	<Book id="22345" publisher="Apress">
		<Title>XML XSLT Guide</Title>
		<Author>Tim Gibson</Author>
		<BookReleaseDate>20-May-2010</BookReleaseDate>
	</Book>	
</Books>

In case the publisher was modeled as a XML element, it could further on easily evolve into Extension-2.xml or Extension-3.xml.

<!-- Extension-2.xml -->
<Books>
	<Book id="12345">
		<Title>XML Modeling - An approach</Title>
		<Author>Ray Johnson</Author>
		<BookReleaseDate>20-March-2001</BookReleaseDate>
		<Publisher>
			<Name>McGraw Hill</Name>
			<Location>Seattle</Location>
		</Publisher>		
	</Book>
	<Book id="22345">
		<Title>XML XSLT Guide</Title>
		<Author>Tim Gibson</Author>
		<BookReleaseDate>20-May-2010</BookReleaseDate>
		<Publisher>
			<Name>Apress</Name>
			<Location>Florida</Location>
		</Publisher>	
	</Book>	
</Books>

<!-- Extension-3.xml -->
<Books>
	<Book id="12345" publisherid="12">
		<Title>XML Modeling - An approach</Title>
		<Author>Ray Johnson</Author>
		<BookReleaseDate>20-March-2001</BookReleaseDate>
	</Book>
		<Book id="22345" publisherid="13">
		<Title>XML XSLT Guide</Title>
		<Author>Tim Gibson</Author>
		<BookReleaseDate>20-May-2010</BookReleaseDate>
	</Book>	
	<Publisher id="12">
		<Name>McGraw Hill</Name>
		<Location>Seattle</Location>
	</Publisher>
		<Publisher id="13">
		<Name>Apress</Name>
		<Location>Florida</Location>
	</Publisher>
</Books>

Relationship with parent element

Any data member which shares a one-to-one relationship with the parent element can be modeled as an attribute, provided the containment relationship between the parent element is weak. A Person and FirstName have a strong containment relationship, a Book and Publisher do not necessarily share a strong containment relationship. If the relationship is one-to-many, that element necessairly needs to be modeled as a XML element. While modeling a person who is an insurance agent, his/her agent number can be modeled as an attribute, however the states in which he/she are licensed to sell insurance can be more than one. Hence the states need to be modeled as XML element.

<?xml version="1.0" encoding="UTF-8"?>
<Persons>
	<Person agentNbr="23456">
		<FirstName>Harry</FirstName>
		<LastName>Maxwell</LastName>
		<LicenseState>VA</LicenseState>
		<LicenseState>GA</LicenseState>
		<LicenseState>FL</LicenseState>
	</Person>
</Persons>

Modeling Relationships

While explaining the extensibility point I used two sample XMLs Extension-2.xml and Extension-3.xml. In Extension-2.xml the Publisher element was made a child element of Book. In Extension-3.xml, the Publisher element was retained as a separate data structure within the root element and its id was modeled as an attribute in Book element. Extension-3.xml provides a flexible structure where I can reuse the same publisher element across multiple Books. Therefore when relationships are not modeled as container relationships(e.g. Extension-2.xml) and a reference is provided at one end of the relationship, the reference can be modeled as a attribute.

Who’s the information consumer?

One key criteria to consider is who is the potential consumer of the information? Is it a human or is it a machine? If it is a machine, the data member can be modeled as an attribute, while a human being would find element preferable due to readability. Machines usually consume meta-data, while humans consume data.
This point might have some overlap with the data or metadata point. I just wanted to highlight it.

Is member order/sequence important?

In some cases maintaining data in specific order is important. Elements support maintenance of ordered sequence, attributes do not.

Some Useful references:

http://xml.coverpages.org/elementsAndAttrs.html
http://xml.coverpages.org/elementAttr9804.html

My first two tutorials in this series covered a simple HelloWorld and provided an insight into development of a simple android based mobile application (mobile app). In this blog post I intended to skim below the surface and take a look at the various layout formats supported by the Android 4.0 platform. My development platform as discussed in Part 1 HelloWorld blog post remains unchanged.

Android allows definition of its UI in two ways, defining UI elements, their layout declaratively in a XML or programmatically adding UI elements with layout information using Java programming language. I intend to cover both the methods of UI creation. The Android 4.0 platform supports the following layout formats:

• FrameLayout
• LinearLayout
• ListView
• GridView
• TableLayout
• RelativeLayout
• TabLayout

In the subsequent paragraphs, I will be explaining each layout, its configuration settings and wherever possible detail out how to implement the layout declaratively and programmatically. Before starting, let me describe the common resources for the subsequent discussion. They are colors.xml and strings.xml located within the /res/values folder.

colors.xml

<?xml version="1.0" encoding="utf-8"?>
<resources>
        <color name="white">#ffffffff</color>
        <color name="red">#ffff0000</color>
        <color name="black">#ff000000</color>
        <color name="blue">#ff0000ff</color>
        <color name="green">#ff00ff00</color>
        <color name="cyan">#ff00ffff</color>
        <color name="dkgray">#ff444444</color>
        <color name="gray">#ff888888</color> 
</resources>

strings.xml

<?xml version="1.0" encoding="utf-8"?>
<resources>
    <string name="hello">Hello World, LayoutDemoActivity!</string>
    <string name="app_name">Layout Demonstrator</string>
    <string name="usernamelbl">UserNameLabel</string>
    <string name="usernamefld">usernamefld</string>
    <string name="passwordfld">passwordfld</string>
    <string name="passwordlbl">passwordlbl</string>

    <!-- FrameLayout starts -->    
    <string name="firstview">My First View</string>
    <string name="secondview">My Second View</string>    
    <!-- FrameLayout ends -->    
    
    <!-- LinearLayout starts -->    
    <string name="one">One</string>
    <string name="two">Two</string>
    <string name="three">Three</string>    
    <!-- LinearLayout ends -->   
    
    <!-- TableLayout starts -->    
    <string name="calchint">Enter your input</string>
    <string name="onefigure">1</string>
    <string name="twofigure">2</string>
    <string name="threefigure">3</string>
    <string name="eqfigure">=</string>
    <!-- TableLayout ends -->   
     
    <!-- RelativeLayout starts -->
    <string name="username">User name:</string>
    <string name="password">Password:</string>
    <string name="login">Log In</string>
    <!-- RelativeLayout ends -->
</resources>

I will explain the significance and application of the two XMLs individual entries during the walk thru of individual layout. Let’s look at the first layout, FrameLayout.

FrameLayout

The FrameLayout is the simplest of all layouts. It is designed to contain and display only one UI element. Addition of multiple UI elements will just cause the subsequent elements to overlay above the previous element(s). Following is the source of framelayout.xml which is FrameLayout’s declarative implementation:

<?xml version="1.0" encoding="utf-8"?>
<FrameLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="fill_parent"
    android:layout_height="fill_parent">

    <TextView
        android:layout_width="fill_parent"
        android:layout_height="wrap_content"
        android:text="@string/firstview" />

    <TextView
        android:layout_width="fill_parent"
        android:layout_height="wrap_content"
        android:text="@string/secondview" />
    
</FrameLayout>

The root element FrameLayout defines that UI window will be presented using the FrameLayout format. The attributes layout_width and layout_height prescribe the width and height for the layout container. In the XML we have defined the value of two attributes as ‘fill_parent’ which means that the layout container is expected to cover the available screen real estate. Alternatively the developer is free to define specific dimensions in the following units: px(pixels), dp(density-independent pixels) and sp(scaled pixels based on preferred font size), in(inches) and mm (millimeters). An elaborate explanation on the various units is available here.

Next I have defined a TextView UI element. The layout_height attribute is defined as ‘wrap_content’ which means that the height of the TextView component depends on the length of the component’s text message. The text message is defined by the value of android:text attribute. The value can be the text message string or a pointer to the name attribute of string defined in strings.xml. In our case, it is a pointer to the string named ‘firstview’, the syntax format is @string/{name}. In addition to the firstview TextView component we have defined another TextView component named secondview. The code associated with the second TextView is commented out. This is specifically done to showcase the impact of adding more than one UI components in FrameLayout. Run the code leaving secondview element definition commented. So how do we run code? My Android project name is LayoutDemo. During Android project creation, eclipse creates a Activity class named LayoutDemoActivity. Please find below the source code of LayoutDemoActivity class.

package com.android.layout;

import android.app.Activity;
import android.os.Bundle;

public class LayoutDemoActivity extends Activity {
    /** Called when the activity is first created. */
    @Override
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.main);
    }
}

Change line number 11 to the following:

setContentView(R.layout.framelayout);

To understand intricacies of the generated class R refer to Satya Komatineni’s blog post ‘Understanding R.java’.

The changed source code causes LayoutDemoActivity class to use the framelayout.xml as its content. To run the LayoutDemoActivity class do the following. Within the project, search and open the AndroidManifest.xml. Check if the manifest file has the following entry, if not add it.

        <activity
            android:label="@string/app_name"
            android:name=".LayoutDemoActivity" >
            <intent-filter >
                <action android:name="android.intent.action.MAIN" />

                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
        </activity>

Please note one thing. The top element of the manifest file is defined as follows:

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.android.layout"
    android:versionCode="1"
    android:versionName="1.0" >

Refer the package attribute value. The complete class name is derived by concatenating package attribute value of manifest element and value of android:name attribute of activity element; therefore we have ‘com.android.layout’ + ‘.LayoutDemoActivity’ which becomes com.android.layout.LayoutDemoActivity. Hence the activity name attribute always begin with a ‘.’. Do keep this in mind in case you intend to modularize based on package name and keep Activity classes under different packages.

In the Eclipse menu select Run –> Run Configurations. In the left pane within Android application select ‘LayoutDemo’(this can be any name you may have provided). In the right pane under the ‘Android’ tab in Launch Action select the Launch radio button. Within the drop-down choices select ‘com.android.layout.LayoutDemoActivity’. The application should open in the AVD. The text message ‘My First View’ should be displayed. There’s the output.

Uncomment the secondview TextView and run the application again. The text message will appear garbled as the two TextView contents will overlap. Now that we have covered the declarative programming part, let’s look at the programmatic option.

Here’s the source code of FrameLayoutActivity class.

package com.android.layout;

import android.app.Activity;
import android.os.Bundle;
import android.widget.FrameLayout;
import android.widget.TextView;

public class FrameLayoutActivity extends Activity {
	
	@Override
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
                
        TextView view1 = new TextView(this);
        view1.setText(R.string.firstview);

        TextView view2 = new TextView(this);
        view2.setText(R.string.secondview);
        
        FrameLayout frame = new FrameLayout(this);
        frame.addView(view1);
        //frame.addView(view2);
        
        setContentView(frame);
    }
}

In Java world environment, the generated R.class is used to reference application resources.
Note that there is android.R class which holds platform specific resource values. The R.class you need will be part of your custom package which in my case is com.android.layout package. The R class reference format is R.{resourceType}.{resourceName}, hence we have R.string.firstview at line number 15 in source code.

Add the entry for FrameLayoutActivity in Android manifest file.

        <activity 
            android:label="@string/app_name"
            android:name=".FrameLayoutActivity">
            <intent-filter >
                <action android:name="android.intent.action.MAIN" />

                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
        </activity>

Run the FrameLayoutActivity class using the same method as mentioned for running LayoutDemoActivity. Instead of selecting LayoutDemoActivity as the launch class select FrameLayoutActivity. In the source code note line number 22 which comments out view2. Uncomment the line and run the application to understand the impact of having more than one UI components in FrameLayout.

LinearLayout

The next layout we look at is LinearLayout. This layout container lays out its children aligned to a particular orientation either horizontal or vertical. The developer needs to define the orientation and the children components are laid out horizontally one besides the other or vertically one below the other.

Here’s how you define LinearLayout declaratively. Refer linearlayout.xml

<?xml version="1.0" encoding="utf-8"?>
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="fill_parent"
    android:layout_height="fill_parent"
    android:orientation="vertical">

    <TextView
        android:layout_width="100dp"
        android:layout_height="wrap_content"
        android:text="@string/one" 
        android:background="@color/red"
        android:textColor="@color/cyan"
        android:gravity="left"
        android:textStyle="bold"
        android:layout_gravity="left" 
        android:layout_weight="0"
        android:layout_marginLeft="5dp"
        android:layout_marginTop="5dp"
        android:layout_marginBottom="5dp" />
       
    <TextView
        android:layout_width="100dp"
        android:layout_height="wrap_content"
        android:text="@string/two" 
        android:background="@color/green"
        android:textColor="#ff000000"
        android:gravity="center"
        android:typeface="sans"
        android:textStyle="bold|italic"
        android:layout_gravity="center" 
        android:layout_weight="0"
        android:layout_marginLeft="5dp"
        android:layout_marginTop="5dp"
        android:layout_marginBottom="5dp"
        android:layout_marginRight="5dp"/>
        
    <TextView
        android:layout_width="100dp"
        android:layout_height="wrap_content"
        android:text="@string/three" 
        android:background="@color/blue"
        android:textColor="@color/white"
        android:gravity="right"
        android:typeface="serif"
        android:textStyle="italic"
        android:layout_gravity="right" 
        android:layout_weight="0"
        android:layout_marginLeft="5dp"
        android:layout_marginTop="5dp"
        android:layout_marginBottom="5dp"
        android:layout_marginRight="5dp"/>
</LinearLayout>

• android:orientation – The orientation of the LinearLayout is determined by the value specified for this attribute. The valid options are vertical and horizontal. For our example we are using vertical orientation.
• android:layout_width – This attribute defines the width of the TextView. The TextView also defines another attribute named android:width. Apparently both attributes achieve the same thing, defining width dimension of the TextView.
• android:layout_height – The layout_height defines the height of the TextView component, presently it is defined as ‘wrap_content’, so as to size it to the text contents of the TextView component.
• android:text – already explained earlier.
• android:background – This attribute assigns the background color to the TextView. We can assign a color from the application resources colors.xml. The resource reference format is @color/{name}. Alternatively color can be directly assigned as done for textColor of the second TextView, refer line number 26. The color value is a hexadecimal value in the Alpha-Red-Green-Blue (#AARRGGBB) format.
• android:textColor – This attribute assigns color to the text content of TextView. Value assignment is similar to the background attribute.
• android:gravity – This attribute defines the orientation of text message vis-a-vis the TextView layout. For our example we have provided left aligned orientation.
• android:typeface – This attribute defines the font used by the text content of TextView. The valid options are normal, sans, serif, monospace.
• android:textStyle – This attribute defines the text styling such as bold, italic etc. In case you want to apply two styles together, use the | and assign both values to textStyle attribute. Refer line number 29 for ready reference.
• android:layout_gravity – This attribute defines the orientation of the TextView component. Note the layout_gravity takes care of the TextView component orientation, while the gravity attribute takes care of TextView’s text content’s orientation, a vital difference. To understand further details refer Sandip Chitale’s blog post.
• android:layout_weight – This attribute determines how the space leftover after laying out all components is distributed amongst the components. The attribute accepts a numeric value. To get a better insight refer Mayra’s excellent answer in stackoverflow.com.
• android:layout_marginLeft, bandroid:layout_marginRight,
  android:layout_marginTop, android:layout_marginBottom – These attributes determine the left, right, top and bottom margin settings for the TextView component. The units are same as the ones defined for width or height.

In the example, I have created three TextViews with varying attribute settings to showcase the various configurations. Play around with layout_weight values to understand the impact of this attribute. Here’s the output of the linearlayout.xml:

For programmatic implementation refer to the LinearLayoutActivity class below:

package com.android.layout;

import android.app.Activity;
import android.graphics.Color;
import android.graphics.Typeface;
import android.os.Bundle;
import android.view.Gravity;
import android.view.ViewGroup;
import android.widget.LinearLayout;
import android.widget.TextView;

public class LinearLayoutActivity extends Activity {
	
	@Override
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        
        TextView view1 = new TextView(this);
        view1.setText(R.string.one);
        view1.setBackgroundResource(R.color.red);
        view1.setTextColor(Color.CYAN);
        view1.setGravity(Gravity.LEFT);
        view1.setTypeface(Typeface.DEFAULT_BOLD);
        
        TextView view2 = new TextView(this);
        view2.setText(R.string.two);
        view2.setBackgroundResource(R.color.green);
        //view2.setBackgroundColor(0xffff0000);
        view2.setTextColor(0xff000000);
        view2.setGravity(Gravity.CENTER);
        view2.setTypeface(Typeface.SANS_SERIF, Typeface.BOLD_ITALIC);

        TextView view3 = new TextView(this);
        view3.setText(R.string.three);
        view3.setBackgroundResource(R.color.blue);
        view3.setTextColor(getResources().getColor(R.color.white));
        view3.setGravity(Gravity.RIGHT);
        view3.setTypeface(Typeface.SERIF, Typeface.ITALIC);
        
        LinearLayout layout = new LinearLayout(this);
        layout.setOrientation(LinearLayout.VERTICAL);
        
        LinearLayout.LayoutParams params = new LinearLayout.LayoutParams(
        		LinearLayout.LayoutParams.FILL_PARENT, LinearLayout.LayoutParams.FILL_PARENT);
        layout.setLayoutParams(params);
        
        LinearLayout.LayoutParams params1  = new LinearLayout.LayoutParams(100, 
                ViewGroup.LayoutParams.WRAP_CONTENT,0);
        params1.gravity = Gravity.LEFT;
        params1.weight = 0;
        params1.leftMargin = 5;
        params1.topMargin = 5;
        params1.bottomMargin = 5;
        
        LinearLayout.LayoutParams params2  = new LinearLayout.LayoutParams(100, 
                ViewGroup.LayoutParams.WRAP_CONTENT,0);
        params2.gravity = Gravity.CENTER;
        params2.weight = 0;
        params2.leftMargin = 5;
        params2.topMargin = 5;
        params2.bottomMargin = 5;
        params2.rightMargin = 5;
        
        LinearLayout.LayoutParams params3  = new LinearLayout.LayoutParams(100, 
                ViewGroup.LayoutParams.WRAP_CONTENT,0);
        params3.gravity = Gravity.RIGHT;
        params3.weight = 0;
        params3.leftMargin = 5;
        params3.topMargin = 5;
        params3.bottomMargin = 5;
        params3.rightMargin = 5;
        
        layout.addView(view1, params1);
        layout.addView(view2, params2);
        layout.addView(view3, params3);
        
        setContentView(layout);
    }
}

The following list summarizes relationship between the XML attributes and UI component Class’s methods.

For LinearLayout:

• android:layout_weight, android:layout_height – The width and height are constructor arguments of inner class LayoutParams of LinearLayout. Refer code between line number 43 and 45.
• android:orientation – This XML attribute maps to instance method setOrientation on LinearLayout class. Refer line number 41

For TextView:

• android:text – This attribute maps to instance method setText on TextView. Refer line number 26. The setText method is overloaded and allows two arguments one is an actual text string and the other is reference to application string resource.
• android:background – This attribute maps to two methods of the TextView namely setBackgroundColor and setBackgroundResource. The first method allows setting of color directly, refer commented line number 28 and second allows pointing to application color resource refer line number 35.
• android:textColor – This attribute maps to setTextColor method of TextView. The method accepts the actual color value(line number 21, 29) or the application resource color reference (line number 36). Sadly there is no setTextColorResource method available, hence the convoluted way of setting text color using a resource.
• android:gravity – This attribute maps to setGravity method of TextView. It accepts int argument. Use android.view.Gravity class’s static final int values (line number 22, 30, 37).
• android:typeface, android:textStyle – This attribute maps to TextView’s setTypeface method. The setTypeface method is overloaded to accept only typeface or a combination of typeface and text style (line number 23, 31, 38).

We have so far covered attributes directly mapping to the TextView class. There are some other XML attributes which do not directly map to the TextView class. For these, an instance of LinearLayout.LayoutParams needs to be created and its appropriate properties need to be set.

• android:layout_width, android:layout_height, android:layout_weight – These attributes are constructor arguments of the LinearLayout.LayoutParams(line number 43-44). The layout_weight attribute also maps to weight property of LayoutParams class(line number 50).
• android:layout_gravity – This attribute maps to the gravity attribute of LayoutParams(line number 49, 57). Note this is the gravity orientation for the TextView component within the LinearLayout container.
• android:layout_margin* – These attributes map to the *Margin properties of LayoutParams class(line number 59 to line number 62).

The association of an instance of LinearLayout.LayoutParams with its component is achieved via the layout’s addView method which accepts the UI component and LayoutParams as its input arguments(line number 73 to 75).

An important note: The dimensional setter methods such as setHeight, setWidth accept int input parameters. The input parameter accept pixel values. The dimension in xml definition were defined in dp. Hence a conversion is necessary. Android provides a ready utility class TypedValue to achieve the conversion. Refer its method applyDimension; here’s a sample for reference. I have purposely chosen to avoid this implementation for code legibility, however in practice it is expected that the developer takes care of this to ensure UI consistency across devices.

ListView

ListView displays a list of scrollable items which the user can select. Typically the selection is used to trigger some subsequent processs or activity. The following example uses a combination of declarative and programming elements to implement Android ListView.

Refer to the listlayout.xml.

<?xml version="1.0" encoding="utf-8"?>
<ListView xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="fill_parent"
    android:layout_height="fill_parent"
    android:id="@+id/list">
</ListView>

The ListView is defined in the listlayout.xml. The next step is to provide data to the view. This is achieved by implementing an adapter. Android provides a ready-to-use ArrayAdapter for simple strings etc. Alternatively the developer can subclass BaseAdapter and implement a custom Adapter. My aim is to create a list which displays images and their corresponding names. Find below source code of my custom Adapter CustomImageListAdapter.

package com.android.adapter;

import com.android.layout.R;

import android.content.Context;
import android.graphics.Typeface;
import android.view.Gravity;
import android.view.View;
import android.view.ViewGroup;
import android.view.ViewGroup.LayoutParams;
import android.widget.BaseAdapter;
import android.widget.ImageView;
import android.widget.ImageView.ScaleType;
import android.widget.LinearLayout;
import android.widget.TextView;

public class CustomImageListAdapter extends BaseAdapter {

	private int[] images = {R.drawable.autumnwalk, R.drawable.bridge, R.drawable.butterfly,
			R.drawable.cheetah, R.drawable.cloud, R.drawable.highway, R.drawable.martini,
			R.drawable.rocksculpture, R.drawable.skyatsunset, R.drawable.slicedorange,
			R.drawable.smoke, R.drawable.tulips};
	
	private String[] imageDesc = { "Autumn Walk", "Bridge",
			"Butterfly", "Cheetah", "Cloud", "Highway", "Martini", 
			"Rock Sculpture", "Sky at Sunset", "Sliced Orange", "Smoke",
			"Tulips"};
	
	private Context ctx = null;
	
	public CustomImageListAdapter(Context context) {
		this.ctx = context;
	}
	
	@Override
	public int getCount() {
		return images.length;
	}

	@Override
	public Object getItem(int arg0) {
		return null;
	}

	@Override
	public long getItemId(int arg0) {
		return 0;
	}

	@Override
	public View getView(int arg0, View arg1, ViewGroup arg2) {
		
		ImageView imgView = new ImageView(this.ctx);
		imgView.setScaleType(ScaleType.FIT_CENTER);
		imgView.setPadding(8, 8, 8, 8);
		imgView.setImageResource(images[arg0]);
		imgView.setAdjustViewBounds(Boolean.TRUE);
		imgView.setContentDescription(imageDesc[arg0]);
		imgView.setMaxHeight(200);
		imgView.setMaxWidth(200);

		TextView tv = new TextView(this.ctx);
		tv.setText(imageDesc[arg0]);
		tv.setMaxHeight(100);
		tv.setTypeface(Typeface.DEFAULT, Typeface.BOLD);
		tv.setGravity(Gravity.CENTER);
		tv.setTextColor(this.ctx.getResources().getColor(R.color.white));
		
		LinearLayout layoutView = new LinearLayout(this.ctx);
		layoutView.setOrientation(LinearLayout.HORIZONTAL);
		LinearLayout.LayoutParams params1 = new LinearLayout.LayoutParams(150, 150);
		layoutView.addView(imgView, params1);
		LinearLayout.LayoutParams params2 = new LinearLayout.LayoutParams(
				LayoutParams.FILL_PARENT, LayoutParams.FILL_PARENT);
		layoutView.addView(tv, params2);
		
		return layoutView;
	}

}

The images array holds image references for our application. All images are courtesy stockvault. The actual images are stored in the res/drawable folder. The image descriptions are held in the imageDesc string array. The CustomImageListAdapter’s constructor accepts Context as input argument.
The overridden getView method is the most crucial implementation of the Adapter.The getView method is responsible for creating the individual row of the ListView.

The getView implementation creates a LinearLayout of horizontal orientation containing two UI components ImageView and TextView. To understand the finer details of ImageView setScaleType method refer this blog post. ImageView’s setImageResource associates image application resource reference to view. The setContentDescription is used to set its description. The rest of the code is self-explanatory or has already been covered in the earlier sections.

For displaying use the following ListViewSupplementActivity class.

package com.android.layout.dynamic;

import com.android.adapter.CustomImageListAdapter;
import com.android.layout.R;

import android.app.Activity;
import android.os.Bundle;
import android.widget.ListView;

public class ListViewSupplementActivity extends Activity {
	
	@Override
	public void onCreate(Bundle savedInstanceState) {
		super.onCreate(savedInstanceState);
		this.setContentView(R.layout.listlayout);
		ListView view = (ListView) findViewById(R.id.list);
		view.setAdapter(new CustomImageListAdapter(this));
		
	}

}

The setContentView method sets the listlayout.xml as the content view. The method findViewById is used to retrieve the ListView component and the view’s setAdapter is invoked to associate the CustomImageListAdapter to the view.

To run select ListViewSupplementActivity in Eclipse –> Run Configurations’s launch option. Ensure that the android manifest file has the following entry:

        <activity 
            android:label="@string/app_name"
            android:name=".ListViewLayoutActivity">
            <intent-filter >
                <action android:name="android.intent.action.MAIN" />

                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
        </activity>

The generated output is

GridView

The ListView displays a scrollable single column list. GridView on the other hand displays a scrollable grid of m columns and n rows. ListView is one dimensional, GridView are two dimensional. Like the ListView, the declarative portion of GridView is minimal. Refer the gridlayout.xml.

<?xml version="1.0" encoding="utf-8"?>
<GridView xmlns:android="http://schemas.android.com/apk/res/android"
    android:id="@+id/grid"
    android:layout_width="fill_parent"
    android:layout_height="fill_parent"
    android:numColumns="2"
    android:verticalSpacing="10dp"
    android:horizontalSpacing="10dp"
    android:scrollbarStyle="outsideOverlay"
    android:verticalScrollbarPosition="right"
    android:scrollbars="vertical">
</GridView>

The layout_width and layout_height XML attributes are familiar. The andriod:numColumns defines the number of columns of the grid. For our example we are looking for a two column grid, therefore the value for numColumns is 2. The android:verticalSpacing and android:horizontalSpacing attributes define the vertical and horizontal spacing of the GridView container. The rest of the attributes i.e. scrollbarStyle, verticalScrollbarPosition and scrollbars are associated with styling, position and display of the grid scrollbar.

To run the GridView create the GridViewSupplementActivity class.

package com.android.layout.dynamic;

import com.android.adapter.CustomImageAdapter;
import com.android.layout.R;

import android.app.Activity;
import android.os.Bundle;
import android.util.DisplayMetrics;
import android.view.Gravity;
import android.view.MotionEvent;
import android.view.View;
import android.view.View.OnTouchListener;
import android.widget.AdapterView;
import android.widget.GridView;
import android.widget.Toast;
import android.widget.AdapterView.OnItemClickListener;

public class GridViewSupplementActivity extends Activity {

	private float positionX = 0f;
	private float positionY = 0f;
	
	@Override
	public void onCreate(Bundle savedInstanceState) {
		super.onCreate(savedInstanceState);
		this.setContentView(R.layout.gridlayout);
		
		GridView grid = (GridView)findViewById(R.id.grid);
		grid.setAdapter(new CustomImageAdapter(this));
		
		grid.setOnTouchListener(new OnTouchListener() {
			
			public boolean onTouch(View v, MotionEvent event) {
				
				GridViewSupplementActivity.this.positionX = event.getX();
				GridViewSupplementActivity.this.positionY = event.getY();
				return false;
			}
		});
		
		grid.setOnItemClickListener(new OnItemClickListener() {
	        public void onItemClick(AdapterView<?> parent, View v, int position, long id) {
	    		
	        	DisplayMetrics dm = new DisplayMetrics();
	        	GridViewSupplementActivity.this.getWindowManager().getDefaultDisplay().getMetrics(dm);

	        	int yOffset = dm.heightPixels - parent.getMeasuredHeight();
	        	
	        	GridViewSupplementActivity.this.positionY = GridViewSupplementActivity.this.positionY - 2*yOffset; //position X remains unchanged.
	    			        	
	            Toast t = Toast.makeText(GridViewSupplementActivity.this, v.getContentDescription(), Toast.LENGTH_SHORT);
	            t.setGravity(Gravity.LEFT, (int)GridViewSupplementActivity.this.positionX, 
	            		(int)GridViewSupplementActivity.this.positionY);
	            
	            t.show();
	        }
		});
		
		
	}

}

Line number 26 in GridViewSupplementActivity assigns gridlayout.xml as the Activity’s content. The grid is populated using an Adapter CustomImageAdapter. Refer the adapter’s source code.

package com.android.adapter;

import com.android.layout.R;

import android.content.Context;
import android.view.View;
import android.view.ViewGroup;
import android.widget.BaseAdapter;
import android.widget.ImageView;
import android.widget.ImageView.ScaleType;

public class CustomImageAdapter extends BaseAdapter {

	private int[] images = {R.drawable.autumnwalk, R.drawable.bridge, R.drawable.butterfly,
			R.drawable.cheetah, R.drawable.cloud, R.drawable.highway, R.drawable.martini,
			R.drawable.rocksculpture, R.drawable.skyatsunset, R.drawable.slicedorange,
			R.drawable.smoke, R.drawable.tulips};
	
	private String[] imageDesc = { "Autumn Walk", "Bridge",
			"Butterfly", "Cheetah", "Cloud", "Highway", "Martini", 
			"Rock Sculpture", "Sky at Sunset", "Sliced Orange", "Smoke",
			"Tulips"};
	
	private Context ctx = null;
	
	public CustomImageAdapter(Context context) {
		this.ctx = context;
	}
	
	@Override
	public int getCount() {
		return images.length;
	}

	@Override
	public Object getItem(int arg0) {
		return null;
	}

	@Override
	public long getItemId(int arg0) {
		return 0;
	}

	@Override
	public View getView(int arg0, View arg1, ViewGroup arg2) {
		ImageView imgView = new ImageView(this.ctx);
		imgView.setScaleType(ScaleType.FIT_END);
		imgView.setPadding(8, 8, 8, 8);
		imgView.setImageResource(images[arg0]);
		imgView.setAdjustViewBounds(Boolean.TRUE);
		imgView.setContentDescription(imageDesc[arg0]);
		imgView.setMaxHeight(100);
		imgView.setMaxWidth(100);
		
		return imgView;
	}

}

The implementation is similar to the earlier CustomImageListAdapter. Instead of having a LinearLayout with ImageView and TextView as its constituents, this adapter only creates an ImageView.

So far the layouts used as examples did not have any dynamic behavior. In grid view I intend to add some dynamic behavior, here on clicking an image, the description of the image will be displayed for a short period of time. To implement this functionality, we have implemented two listeners one is onTouchListener and the other is OnItemClickListener. The OnTouchListener is responsible for gathering X and Y co-ordinate position of the touch. The OnItemClickListener is responsible for creating a Toast which is display the image description at the specified co-ordinates. Note that the onTouch method returns false; this ensures that the event continues to be propogated and the OnItemClickListener can be triggered. The X co-ordinate position is not a problem however I was unable to fix up the Y co-ordinate position. I am sure the computation I have used for Y co-ordinate is screen specific but could not find any screen independent solution. Here are two references I used : 1 and 2.

To run the GridViewSupplementActivity class go to Eclipse Menu –> Run Configurations. Select ‘GridViewSupplementActivity’ in the launch drop down. Note for the class to run the following entry should be present in the android manifest file(AndroidManifest.xml).

        <activity 
            android:label="@string/app_name"
            android:name=".dynamic.GridViewSupplementActivity">
            <intent-filter >
                <action android:name="android.intent.action.MAIN" />
                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
        </activity>    

Note the android:name attribute value. If you refer our earlier discussion of the package attribute of the root element manifest, the class name is created appending the package name to the activity attribute name. GridViewSupplementActivity’s complete name is com.android.layout.dynamic.GridViewSupplementActivity. The manifest element’s package attribute value is com.android.layout. Therefore to ensure the validity of the class name the activity attribute name is .dynamic.GridViewSupplementActivity. The same logic applies to ListViewSupplementActivity too.

The output generated is

TableLayout

The TableLayout lays out its consituents into rows and columns. The layout consists of number of TableRow components, each containing one or more Android UI components.
First let’s implement the TableLayout declaratively. Refer the source code of tablelayout.xml

<?xml version="1.0" encoding="utf-8"?>
<TableLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="fill_parent"
    android:layout_height="fill_parent"
    android:stretchColumns="*">
    
    <TableRow>
        
        <TextView
        	android:hint="@string/calchint" 
        	android:gravity="bottom"
        	android:textSize="20dp"
        	android:paddingLeft="5dp"
        	android:paddingTop="0dp"
        	android:paddingRight="0dp"
        	android:paddingBottom="2dp"
        	android:background="@color/white"
        	android:textColorHint="@color/blue"
        	android:textStyle="bold"
        	android:height="40dp"
        	android:layout_marginLeft="5dp"
        	android:layout_marginRight="5dp"
        	android:layout_marginTop="5dp"
        	android:layout_marginBottom="5dp"
        	android:layout_span="3"
        	android:layout_width="fill_parent"/>
        
    </TableRow>
    <TableRow>
        
        <TextView
        	android:text="@string/onefigure"
        	android:textSize="24dp" 
        	android:textStyle="bold"
        	android:background="@color/dkgray"
        	android:textColor="@color/white"
        	android:gravity="center_horizontal"
        	android:layout_marginLeft="5dp"
        	android:layout_marginRight="5dp"/>
        
        <TextView
        	android:text="@string/twofigure"
        	android:textSize="24dp" 
        	android:textStyle="bold"
        	android:background="@color/dkgray"
        	android:textColor="@color/white"
        	android:gravity="center_horizontal"
        	android:layout_marginRight="5dp"/>
        
        <TextView
        	android:text="@string/threefigure"
        	android:textSize="24dp" 
        	android:textStyle="bold"
        	android:background="@color/dkgray"
        	android:textColor="@color/white"
        	android:gravity="center_horizontal"
        	android:layout_marginRight="5dp"/>
        
    </TableRow>
    <TableRow>
        
        <TextView
        	android:text="@string/eqfigure"
        	android:textSize="32dp" 
        	android:textStyle="bold"
        	android:background="@color/gray"
        	android:textColor="@color/white"
        	android:gravity="center_horizontal"
        	android:layout_marginTop="5dp"
        	android:layout_marginRight="5dp"
        	android:layout_column="1" 
        	android:layout_span="2" />
       
    </TableRow>
        
</TableLayout>

In our example we are defining a table with 3 rows and 3 columns. The root element TableLayout has one layout specific attribute stretchColumns. This defines the specific columns which will stretch over the available space in the row. By specifying ‘*’, we have designated all columns to equally use the available space. Alternatively one can specify one or more columns to this attribute. In case of multiple columns use the comma(,) delimiter to specify the columns. In our case ‘*’ can be changed to ’0,1,2′. Note the column number are zero index based.

Next we have defined the first table row containing one TextView. Most of the TextView XML attributes have already been explained in the previous sections, I will focus on those which are new.

• android:hint – The text which appears when the TextView is loaded. Usually acts as a suggestion to the application end user.
• android:textColorHint – Defines the color of the hint text.
• android:layout_span – In some cases content spans multiple columns. In HTML world we have the colspan which determines the number of columns a cell can span. The layout_span attribute implements the same thing. We have defined layout_span as 3 meaning the TextView will span all the three columns in the table.

The following XML attributes are defined in the 3rd TableRow TextView UI component.

• android:layout_column – Allows developer to specify a specific column number within which the UI component will be laid out. In our example, the value provided is 1 meaning the TextView of eqfigure will be laid out in the second column as the span is set to 2, it will cover the second and third columns.

To run the tablelayout.xml do the following change in line number 11 of LayoutDemoActivity class and then run the class.

setContentView(R.layout.tablelayout);

Like stretchColumns TableLayout provides shrinkColumns. The shrinkColumns ensures that columns cover reasonable screen real estate. To get more information about TableLayout and also shrinkColumns refer here.

Now that we have covered the declarative aspect of TableLayout, let’s understand how the same can be implemented programmatically.

package com.android.layout;

import android.app.Activity;
import android.graphics.Color;
import android.graphics.Typeface;
import android.os.Bundle;
import android.view.Gravity;
import android.widget.TableLayout;
import android.widget.TableRow;
import android.widget.TextView;

public class TableLayoutActivity extends Activity {
	
	@Override
    public void onCreate(Bundle savedInstanceState) {
		super.onCreate(savedInstanceState);
		
		TableLayout table = new TableLayout(this);
		TableLayout.LayoutParams params = new TableLayout.LayoutParams();
		params.width = TableLayout.LayoutParams.FILL_PARENT;
		params.height = TableLayout.LayoutParams.FILL_PARENT;
		table.setLayoutParams(params);
		table.setStretchAllColumns(Boolean.TRUE);
		
		TableRow displayRow = new TableRow(this);
		
		TextView calculatorDisplay = new TextView(this);
		calculatorDisplay.setHint(R.string.calchint);
		calculatorDisplay.setGravity(Gravity.BOTTOM);
		calculatorDisplay.setTextSize(20);
		calculatorDisplay.setPadding(5, 0, 0, 2);
		calculatorDisplay.setBackgroundResource(R.color.white);
		calculatorDisplay.setHintTextColor(getResources().getColor(R.color.blue));
		calculatorDisplay.setTypeface(null,Typeface.BOLD);
		calculatorDisplay.setHeight(40);
		
		TableRow.LayoutParams rowParams = new TableRow.LayoutParams();
		rowParams.span = 3;
		rowParams.leftMargin = 5;
		rowParams.rightMargin = 5;
		rowParams.topMargin = 5;
		rowParams.bottomMargin = 5;
		
		displayRow.addView(calculatorDisplay, rowParams);
		
		table.addView(displayRow);
		
		TableRow.LayoutParams leftViewParams = new TableRow.LayoutParams();
		leftViewParams.leftMargin = 5;
		leftViewParams.rightMargin = 5;

		TableRow.LayoutParams viewParams = new TableRow.LayoutParams();
		viewParams.rightMargin = 5;

		
		TableRow row1 = new TableRow(this);
		TextView view1 = new TextView(this);
		view1.setText(R.string.onefigure);
		view1.setTextSize(24);
		view1.setTypeface(null,Typeface.BOLD);
		view1.setBackgroundColor(Color.DKGRAY);
		view1.setTextColor(getResources().getColor(R.color.white));
		view1.setGravity(Gravity.CENTER_HORIZONTAL);
		row1.addView(view1, leftViewParams);

		TextView view2 = new TextView(this);
		view2.setText(R.string.twofigure);
		view2.setTextSize(24);
		view2.setTypeface(null,Typeface.BOLD);
		view2.setBackgroundColor(Color.DKGRAY);
		view2.setTextColor(getResources().getColor(R.color.white));
		view2.setGravity(Gravity.CENTER_HORIZONTAL);
		row1.addView(view2, viewParams);
		
		TextView view3 = new TextView(this);
		view3.setText(R.string.threefigure);
		view3.setTextSize(24);
		view3.setTypeface(null,Typeface.BOLD);
		view3.setBackgroundColor(Color.DKGRAY);
		view3.setTextColor(getResources().getColor(R.color.white));
		view3.setGravity(Gravity.CENTER_HORIZONTAL);
		row1.addView(view3, viewParams);

		
		table.addView(row1);
		
		TableRow row2 = new TableRow(this);
		TextView view4 = new TextView(this);
		view4.setText("=");
		view4.setTextSize(32);
		view4.setTypeface(null,Typeface.BOLD);
		view4.setBackgroundColor(Color.GRAY);
		view4.setTextColor(getResources().getColor(R.color.white));
		view4.setGravity(Gravity.CENTER_HORIZONTAL);

		TableRow.LayoutParams calcParams = new TableRow.LayoutParams();
		calcParams.topMargin = 5;
		calcParams.rightMargin = 5;
		calcParams.column = 1;
		calcParams.span = 2;
		
		row2.addView(view4, calcParams);
		
		table.addView(row2);
		
		this.setContentView(table);
	}

}

I will just focus on the specific areas not explained in the previous sections. To implement android:stretchColumns functionality, the TableLayout class provides two methods, one is setStretchAllColumns and the other is setColumnStretchable. Since we needed all columns to be stretchable, we used the first method; refer line number 23 in the source. In case we want specific columns to be made stretchable, we can use the second method, it accepts column number and boolean as input arguments.

TableLayout creation and initialization of its LayoutParams is covered in source code line number 18 to 23. TableRow creation, addition of its constiuents components and their LayoutParams is covered from line number 37-42, 48-53 and 96-100.
The remaining code is self-explanatory. Each TableRow alongwith its LayoutParams is added to the TableLayout via the addView method. TableRow.LayoutParams properties column and span map to XML attributes layout_column and layout_span.

Ensure that TableLayoutActivity is added in the Android Manifest file. Run the class via selecting it in the Launch option to view the results. The output is below

RelativeLayout

The RelativeLayout arranges its child components based on component’s layout positioning definition relative to one another. Each component can be laid out above, below, to the left or right of another component. A combination of positional rules such as right of X component and below Y component can also be applied. To gain an understanding let’s look at the declarative implementation of the layout in relativelayout.xml

<?xml version="1.0" encoding="utf-8"?>
<RelativeLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="300dp"
    android:layout_height="600dp">

    <TextView
        android:text="@string/username" 
        android:gravity="right"
        android:id="@string/usernamelbl"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:height="40dp"
        android:layout_marginLeft="10dp"
        android:layout_marginTop="10dp"
        android:layout_marginRight="10dp"
        android:layout_marginBottom="10dp" />

   	<EditText
        android:id="@string/usernamefld"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:height="40dp"
        android:width="200dp"
        android:layout_marginLeft="10dp"
        android:layout_marginTop="10dp"
        android:layout_marginRight="10dp"
        android:layout_marginBottom="10dp"
        android:layout_toRightOf="@string/usernamelbl" />
    
    <TextView
        android:id="@string/passwordlbl"
        android:text="@string/password" 
        android:gravity="right"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:layout_below="@string/usernamelbl"
        android:height="40dp"
        android:layout_marginLeft="10dp"
        android:layout_marginTop="10dp"
        android:layout_marginRight="10dp"
        android:layout_marginBottom="10dp" />
   		
   	<EditText
        android:id="@string/passwordfld"
        android:inputType="textPassword"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:height="40dp"
        android:width="200dp"
        android:layout_marginLeft="10dp"
        android:layout_marginTop="10dp"
        android:layout_marginRight="10dp"
        android:layout_marginBottom="10dp"
        android:layout_toRightOf="@string/passwordlbl" 
        android:layout_below="@string/usernamefld"/>
    
   	<Button
   	    android:text="@string/login"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
		android:layout_below="@string/passwordfld"
		android:layout_centerHorizontal="true"   	    
   	    />
    	
</RelativeLayout>

Lets’s understand some newly added XML attributes in the relativelayout.xml. We are trying to develop a simple login page with username, password and submit button.

The first TextView a label field for ‘User Name’ text is defined with attributes which we are aware of. Next EditText to capture the actual value of user input is defined. A positional constraint of the EditText is defined via the android:layout_toRightOf attribute. The value is the application string resource reference for the username TextView. Next we define password label which should be positioned below username label. This is achieved by the android:layout_below attribute. The value assigned is the application string resource reference for the username TextView. The EditText component to accept password input is positioned to the right of password TextView and below username EditText component by using two attributes android:layout_toRightOf and android:layout_below. The last component to be covered in the submit button which is purely positioned as center horizontal to be placed below TextViews and EditTexts. I was a bit surprised that RelativeLayout has a special android:layout_centerHorizontal; my thinking was that android:layout_gravity should have sufficed.

To run the application change line number 11 in LayoutDemoActivity class to the following and launch LayoutDemoActivity in Eclipse Run Configurations:

setContentView(R.layout.relativelayout);

Now let’s look at how this can be implemented programmatically. Have a look at the source code of RelativeLayoutActivity.

package com.android.layout;

import android.app.Activity;
import android.os.Bundle;
import android.text.InputType;
import android.view.Gravity;
import android.widget.Button;
import android.widget.EditText;
import android.widget.RelativeLayout;
import android.widget.RelativeLayout.LayoutParams;
import android.widget.TextView;

public class RelativeLayoutActivity extends Activity {

	private static int HEIGHT = 40;
	
	@Override
	public void onCreate(Bundle savedInstanceState) {
		super.onCreate(savedInstanceState);
	
		RelativeLayout relLayout = new RelativeLayout(this);
		RelativeLayout.LayoutParams params = new RelativeLayout.LayoutParams(300, 600);
		relLayout.setLayoutParams(params);
		TextView userNameLabel = new TextView(this);
		userNameLabel.setText(R.string.username);
		userNameLabel.setGravity(Gravity.RIGHT);
		userNameLabel.setId(R.string.usernamelbl);
		RelativeLayout.LayoutParams params1 = new RelativeLayout.LayoutParams(LayoutParams.WRAP_CONTENT, 
				LayoutParams.WRAP_CONTENT);
		params1.height = HEIGHT;
		params1.setMargins(10, 10, 10, 10);
		relLayout.addView(userNameLabel, params1);
		
		EditText userNameField = new EditText(this);
		userNameField.setId(R.string.usernamefld);
		RelativeLayout.LayoutParams params2 = new RelativeLayout.LayoutParams(LayoutParams.WRAP_CONTENT, 
				LayoutParams.WRAP_CONTENT);
		params2.height = HEIGHT;
		params2.width = 200;
		params2.setMargins(10, 10, 10, 10);
		params2.addRule(RelativeLayout.RIGHT_OF, R.string.usernamelbl);
		relLayout.addView(userNameField, params2);
		
		TextView passwordLabel = new TextView(this);
		passwordLabel.setId(R.string.passwordlbl);
		passwordLabel.setText(R.string.password);
		passwordLabel.setGravity(Gravity.RIGHT);
		RelativeLayout.LayoutParams params3 = new RelativeLayout.LayoutParams(LayoutParams.WRAP_CONTENT, 
				LayoutParams.WRAP_CONTENT);
		params3.addRule(RelativeLayout.BELOW, R.string.usernamelbl);
		params3.height = HEIGHT;
		params3.setMargins(10, 10, 10, 10);
		
		relLayout.addView(passwordLabel, params3);

		EditText pwdField = new EditText(this);
		pwdField.setId(R.string.passwordfld);
		pwdField.setInputType(InputType.TYPE_TEXT_VARIATION_PASSWORD);
		RelativeLayout.LayoutParams params4 = new RelativeLayout.LayoutParams(LayoutParams.WRAP_CONTENT, 
				LayoutParams.WRAP_CONTENT);
		params4.height = HEIGHT;
		params4.width = 200;
		params4.setMargins(10, 10, 10, 10);
		params4.addRule(RelativeLayout.RIGHT_OF, R.string.passwordlbl);
		params4.addRule(RelativeLayout.BELOW, R.string.usernamefld);
		
		relLayout.addView(pwdField, params4);

		Button submit = new Button(this);
		submit.setText(R.string.login);
		RelativeLayout.LayoutParams params5 = new RelativeLayout.LayoutParams(LayoutParams.WRAP_CONTENT, 
				LayoutParams.WRAP_CONTENT);
		params5.addRule(RelativeLayout.BELOW, R.string.passwordfld);
		params5.addRule(RelativeLayout.CENTER_HORIZONTAL);
		relLayout.addView(submit, params5);
		
		this.setContentView(relLayout);
		
		
	}
	
}

The layout positioning constraints are defined in RelativeLayout.LayoutParams class’s addRule method. The method accepts position and applicable component reference as its input arguments. Refer the line numbers 41, 50, 64-65, 73-74.

Run the programmatic or declarative option. The output is

TabLayout

There are applications which need the tabs. Individual tab page logically groups together data. Android implements this using the TabActivity. However do note that the class TabActivity has been deprecated in the favor of Fragments. I tried to understand how Fragments work but could not figure it out. I did find this blog post by Evelina Vrabie. I am still digesting the approach which appears a stretch compared to TabActivity. I need to develop the example using TabActivity and explore Fragments later.

The Tab implementation example is done programmatically. Refer the source code of TabsLayoutActivity class.

package com.android.layout;

import com.android.layout.tab.CoffeeShopListActivity;
import com.android.layout.tab.FoodChainListActivity;
import com.android.layout.tab.RestaurantListActivity;

import android.app.TabActivity;
import android.content.Intent;
import android.content.res.Resources;
import android.os.Bundle;
import android.widget.TabHost;

public class TabsLayoutActivity extends TabActivity {

	public void onCreate(Bundle savedInstanceState) {
		super.onCreate(savedInstanceState);
		
		TabHost tabHost = getTabHost();
		Intent intent = null;
		
		intent = new Intent().setClass(this, RestaurantListActivity.class);
		TabHost.TabSpec spec = tabHost.newTabSpec("restaurants");
		spec.setIndicator("Restaurant");
		spec.setContent(intent);
		tabHost.addTab(spec);
		
		intent = new Intent().setClass(this, FoodChainListActivity.class);
		spec = tabHost.newTabSpec("chains");
		spec.setIndicator("Food Chain");
		spec.setContent(intent);
		tabHost.addTab(spec);
		
		intent = new Intent().setClass(this, CoffeeShopListActivity.class);
		spec = tabHost.newTabSpec("shops");
		spec.setIndicator("Coffee Shop");
		spec.setContent(intent);
		tabHost.addTab(spec);
		
		tabHost.setCurrentTab(1);
		
	}
	
}

Note line number 13 where TabsLayoutActivity extends TabActivity. Access to the underlying TabHost instance which provides the tab functionality is obtained via TabActivity’s getTabHost method. I am planning to develop a tabbed application which displays three tab data. The individual tab categories are restaurant, food chain and coffee shop. Each of the tab can be implemented as a View or Activity. To achieve modular design it is recommended that individual Activity per tab are created. Accordingly I have created three Activity classes RestaurantListActivity, FoodChainListActivity and CoffeeShopListActivity. The source code is below:

package com.android.layout.tab;

import android.R;
import android.app.ListActivity;
import android.os.Bundle;
import android.widget.ArrayAdapter;
import android.widget.ListView;

public class RestaurantListActivity extends ListActivity {

	private static final String[] restaurants = new String[] {
		"Golden Punjab", "Shikara", "The Bowl House", 
		"Copper Chimney", "Gajalee"};
	
	@Override
	public void onCreate(Bundle savedInstanceState) {
		super.onCreate(savedInstanceState);

		ListView view = getListView();
		view.setAdapter(new ArrayAdapter<String>(getBaseContext(), R.layout.simple_list_item_1, restaurants));
		
	}
	
}

package com.android.layout.tab;

import android.R;
import android.app.ListActivity;
import android.os.Bundle;
import android.widget.ArrayAdapter;
import android.widget.ListView;

public class FoodChainListActivity extends ListActivity {

	private static final String[] chains = new String[] {
		"Pizza Hut", "Dominos", "Kailas Parbat", "Malgudi's", 
		"Only Parathas", "KFC"};
	
	@Override
	public void onCreate(Bundle savedInstanceState) {
		super.onCreate(savedInstanceState);
		
		ListView view = getListView();
		view.setAdapter(new ArrayAdapter<String>(getBaseContext(), R.layout.simple_list_item_1, chains));
		
	}	
}

package com.android.layout.tab;

import android.R;
import android.app.ListActivity;
import android.os.Bundle;
import android.widget.ArrayAdapter;
import android.widget.ListView;

public class CoffeeShopListActivity extends ListActivity {

	private static final String[] coffeeShops = new String[] {
		"Barista", "Cafe Coffee Day"};
	
	@Override
	public void onCreate(Bundle savedInstanceState) {
		super.onCreate(savedInstanceState);

		ListView view = getListView();
		view.setAdapter(new ArrayAdapter<String>(getBaseContext(), R.layout.simple_list_item_1, coffeeShops));
		
	}
	
}

Each of the Activity classes consist of a simple ListView with the some instances of the applicable category.

Refer the following lines in TabsLayoutActivity

		intent = new Intent().setClass(this, RestaurantListActivity.class);
		TabHost.TabSpec spec = tabHost.newTabSpec("restaurants");
		spec.setIndicator("Restaurant");
		spec.setContent(intent);
		tabHost.addTab(spec);

Until now in all our examples we have created a single Activity instance and interacted with it. In this example, we will have to switch between TabActivity and the three Activity instances. This is achieved in Android using an Intent class. The class is responsible for transitioning from one Activity to another. In line number 1 we create an Intent for RestaurantListActivity. Later we create a TabSpec. The indicator attribute holds the text label of the tab. The content holds the presentation data and content. By setting the content to intent, we are assigning RestaurantListActivity class to that tab. The same exercise is done with the other two *ListActivity classes.

Edit the Android Manifest file and key in the following entries.

        <activity 
            android:label="@string/app_name"
            android:name=".TabsLayoutActivity">
            <intent-filter >
                <action android:name="android.intent.action.MAIN" />

                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
        </activity>


        <activity android:name=".tab.RestaurantListActivity" />
        <activity android:name=".tab.FoodChainListActivity" />
        <activity android:name=".tab.CoffeeShopListActivity" />   

Run the TabsLayoutActivity class using Eclipse’s Run Configurations.

The output is:

Phew! This has been one long post. This is me signing off.

My development environment remains unchanged to the one mentioned in Part 1 of the Android tutorial series.

Let’s begin by creating a new Android application named Calculator1.0. To create the application, in the eclipse menu select File -> New -> Other -> Android Project. In the project creation wizard enter the following values:

• Project Name: Calculator1.0
• Build Target: Android 4.0
• Application Name: Retain the project name. The developer is free to choose a different name.
• Package Name: com.calculator
• Minimum SDK: 14

The Calculator1.0 project has been created. In the eclipse package explorer, verify if the following folders are created. There should be a src folder which contains com.calculator.CalculatorActivity class. The res folder should have two sub-folders in it namely layout and values. The layout folder will have main.xml file and values folder will have strings.xml.

If the assertions made above are true, the project has been successfully created. Next, let’s proceed to adding the calculator specific functionality to the project. My aim is to create a simple application which accepts two input values and the mathematical operation to be applied on the two values.

Let’s begin by first creating the user interface. To facilitate user interface aspect separation, Android implements user interface using three components, the static definition of user interface in res/layout/main.xml, labeling and aligned aspects in res/values/strings.xml and the dynamic user interface aspects using the com.calculator.CalculatorActivity class.

First let’s begin with res/values/strings.xml. Here’s the source code of strings.xml

<?xml version="1.0" encoding="utf-8"?>
<resources>
    <string name="app_name">Calculator 1.0</string>
    <string name="operation">Select Operation</string>
    <string name="FirstInput">Input 1</string>
    <string name="SecondInput">Input 2</string>
    <string name="welcomeMessage">Welcome to Calculator</string>
    <string name="spacer">----------------------</string>
    <string name="calculate">Calculate</string>
    <string name="opPrompt">Select Operation</string>
    <string-array name="operations">
        <item >Multiply</item>
        <item >Divide</item>
        <item >Add</item>
        <item >Subtract</item>
    </string-array>
    <string name="answer">Answer:</string>
	<string name="textSize">16sp</string>
</resources>

The strings.xml acts as a repository which provides text strings for your application. The app_name resource is created by default; other resources are added as a part of the Calculator application customization. The utilization of the resources defined in the strings.xml will be elaborated upon as a part of the main.xml explanation. Two resources to keep an eye on in strings.xml are operations and textSize. The string array ‘operations’ defines the drop-down string values for the ‘operation’ field of the calculator. The textSize resource was planned to be used for standardizing the text size definition of Android widgets. Unfortunately this did not work. As per research the appropriate method to implement this is using a dimens.xml in values folder. Details are provided here. Will look into that in a subsequent post.

Let’s move on to res/layout/main.xml file.

<?xml version="1.0" encoding="utf-8"?>
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="fill_parent"
    android:layout_height="fill_parent"
    android:orientation="vertical" 
    android:paddingLeft="6px" 
    android:textSize="10sp">

    <TextView
        android:id="@+id/textViewWelcomeMsg"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:text="@string/welcomeMessage"
        android:textAppearance="?android:attr/textAppearanceLarge" 
        android:paddingBottom="10px"/>

    <!-- <TextView
        android:id="@+id/textViewSpacer"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:text="@string/spacer"
        android:textAppearance="?android:attr/textAppearanceLarge" />
	-->

    <TextView
        android:id="@+id/textViewInput1"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:text="@string/FirstInput" />

    <EditText
        android:id="@+id/editTextInput1"
        android:layout_width="fill_parent"
        android:layout_height="wrap_content"
        android:inputType="numberDecimal" 
        android:textSize="16sp" 
        android:hint="Enter first input">
        <requestFocus />
    </EditText>

    <TextView
        android:id="@+id/textViewInput2"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:text="@string/SecondInput" />

    <EditText
        android:id="@+id/editTextInput2"
        android:layout_width="fill_parent"
        android:layout_height="wrap_content"
        android:inputType="numberDecimal"  
        android:textSize="16sp" 
        android:hint="Enter second input"
        />
		
    <Spinner
        android:id="@+id/spinnerOperation"
        android:layout_width="fill_parent"
        android:layout_height="wrap_content"
        android:prompt="@string/opPrompt"  
        android:textSize="14sp"
        android:entries="@array/operations"
        android:drawSelectorOnTop="true"
        android:spinnerMode="dropdown"
        android:dropDownWidth="wrap_content"
       
	/>
    <!-- spinnerMode=dropdown|dialog -->
		
    <Button
        android:id="@+id/buttonCalculate"
        android:layout_width="175px"
        android:layout_height="wrap_content"
        android:text="@string/calculate"
        android:onClick="onCalculateClick" 
        android:textSize="16sp"
        android:layout_gravity="center_horizontal" 
        />

    <TextView
        android:id="@+id/textViewAns"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:text="@string/answer" 
        android:textSize="20sp" 
        android:paddingTop="20px"
        android:textColor="#FFFFFF"/>
</LinearLayout>

The root level element is LinearLayout. The LinearLayout format is one of the many layout formats provided by Android. For details on other formats refer here. The LinearLayout component aligns its constituent components in a single direction i.e. vertically or horizontally. The alignment is dependent on the definition of LinearLayout’s orientation attribute. In our example we have used the vertical alignment. The rest of LinearLayout’s attributes are self-explanatory. In our example we have used four types of Android widgets. The first is the TextView, second is EditText, third Spinner and fourth is Button.

The TextView component displays text to the user. Let’s have a look at the first TextView component defined in the main.xml and its attribute values.

    <TextView
        android:id="@+id/textViewWelcomeMsg"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:text="@string/welcomeMessage"
        android:textAppearance="?android:attr/textAppearanceLarge" 
        android:paddingBottom="10px"/>

The id attribute establishes the unique name of the component. This value is extremely useful in dynamically searching for a specific component. The values associated with layout_width or layout_height are standard and are explained here. The ‘wrap_content’ means that the component will sized just large enough to encapsulate its contents.The value associated to the text attribute is the textual content which is displayed in the user interface. To associate the text attribute’s value with resource defined in the strings.xml we use the special notation of @string/. The value following the / character map to the resource name defined in the strings.xml; in the present case we have @string/welcomeMessage. One more point to notice is the value defined for textAppearance attribute is ?android:attr/textAppearanceLarge. This means we will be using the Android device specific value for textAppearance. There are a number of device specific values available. Details are documented here.

The next component/widget to look at is EditText. Let’s use the EditText component with id editTextInput1 from the main.xml.

    <EditText
        android:id="@+id/editTextInput1"
        android:layout_width="fill_parent"
        android:layout_height="wrap_content"
        android:inputType="numberDecimal" 
        android:textSize="16sp" 
        android:hint="Enter first input">
        <requestFocus />
    </EditText>

EditText enhances the TextView widget by providing the ability to be editable. The next attribute to look at is inputType. We have used inputType value as numberDecimal. This means that the EditText will only accept numeric characters or a decimal character. The inputType supports the following different values. The hint attribute holds the text that is displayed to user before he/she submits any input to the field.

Next let’s look at the third component Spinner.

    <Spinner
        android:id="@+id/spinnerOperation"
        android:layout_width="fill_parent"
        android:layout_height="wrap_content"
        android:prompt="@string/opPrompt"  
        android:textSize="14sp"
        android:entries="@array/operations"
        android:drawSelectorOnTop="true"
        android:spinnerMode="dropdown"
        android:dropDownWidth="wrap_content"     
	/>

The Spinner widget basically provides a control that can display a drop-down list. The prompt attribute contains the text that is displayed on the Spinner. The entries points to an array resource holding all the drop-down values. In our example it refers to the operations string array. The spinnerMode attribute accepts two values drop-down or dialog. Run the application with both modes to understand the difference. The prompt text appears in the drop down in the ‘dialog’ mode and does not appear in the ‘dropdown’ mode. I have not been able to figure out why my drop-down does not appear like a traditional drop-down with a down arrow button, instead there appears a small triangle at the right hand bottom corner of the spinner widget.

The final component is the button.

    <Button
        android:id="@+id/buttonCalculate"
        android:layout_width="175px"
        android:layout_height="wrap_content"
        android:text="@string/calculate"
        android:onClick="onCalculateClick" 
        android:textSize="16sp"
        android:layout_gravity="center_horizontal" 
        />

The user is expected to key in the two input values, select the mathematical operation and click the button to trigger the computation process. The Button provides an attribute layout_gravity to decide the placement of the Button in the UI screen. The possible values for layout_gravity are provided here. To trigger the computation process the Button widget is provided with an attribute onClick which maps to the button click event. The string associated to the onClick method consists of a method implemented on the Activity instance holding the Button widget. The expected method name and signature is

public void onCalculateClick(View view) {
}

To complete the final piece of the Calculator Application, below is the source code of the CalculatorActivity class.

package com.calculator;

import android.app.Activity;
import android.os.Bundle;
import android.view.View;
//import android.widget.ArrayAdapter;
import android.widget.EditText;
import android.widget.Spinner;
import android.widget.TextView;
import android.widget.Toast;

public class CalculatorActivity extends Activity {
	
	private static final String MULTIPLY = "Multiply";
	private static final String DIVIDE   = "Divide";
	private static final String ADD      = "Add";
	private static final String SUBTRACT = "Subtract";
	
    /** Called when the activity is first created. */
    @Override
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.main);
        
        /*Spinner spinner = (Spinner) findViewById(R.id.spinnerOperation);
        ArrayAdapter<CharSequence> adapter = ArrayAdapter.createFromResource(this, R.array.operations,
                android.R.layout.simple_spinner_dropdown_item);
        spinner.setAdapter(adapter);*/
    }
    
    public void onCalculateClick(View view) {
    	switch (view.getId()) {
    	
	    	case R.id.buttonCalculate:
	    		EditText text1 = (EditText)findViewById(R.id.editTextInput1);
	    		String text1Val = text1.getText().toString();
	    		EditText text2 = (EditText)findViewById(R.id.editTextInput2);
	    		String text2Val = text2.getText().toString();
	    		Spinner spinner = (Spinner)findViewById(R.id.spinnerOperation);
	    		String value = (String)spinner.getSelectedItem();
	    		
	    		if (value == null || text1Val == null || text2Val == null) {
	    			Toast.makeText(view.getContext(), "Please select input values.",   Toast.LENGTH_LONG).show();
	    		}
	    		
	    		float input1Val = Float.parseFloat(text1Val);
	    		float input2Val = Float.parseFloat(text2Val);
	    		
	    		
	    		String retVal = calc(input1Val, input2Val, value);
    		
	    		TextView tv = (TextView)findViewById(R.id.textViewAns);
	    		tv.setText("Answer: " + retVal);
    	}
    }
    	
    private String calc(float input1, float input2, String operation) {
		
    	if (MULTIPLY.equals(operation)) {
			return Float.toString(input1 * input2);
		} else if (DIVIDE.equals(operation)) {
			if (input2 == 0) {
				return "Not A Number";
			}
			return Float.toString(input1 / input2);
		} else if (ADD.equals(operation)) {
			return Float.toString(input1 + input2);
		} else if (SUBTRACT.equals(operation)) {
			return Float.toString(input1 - input2);
		}
		
		return "Improper operation!";
	}   
}

The implementation code of the onCalculateClick and calc methods are self-explanatory. Please note the commented out code involving the ArrayAdapter. This is an alternative method for populating the drop-down dynamically.

Overall the structure of the Android application is similar to a Flex application. Probably also to Windows Presentation Foundation or Silverlight application; although I do not have any hands-on experience on those. The added advantage of Android is that one does not have to learn a new programming language unlike Flex where one needs to learn ActionScript.

Run the Android application in the eclipse environment. In case you are rerunning the application, ensure that you do not close the emulator, for details refer here. On trying to start application directly, I experienced a number of errors. Two errors are shown below:

[2011-11-11 23:27:33 - Calculator] Failed to install Calculator.apk on device 'emulator-5554!
[2011-11-11 23:27:33 - Calculator] (null)
[2011-11-11 23:27:33 - Calculator] Launch canceled!

[2011-11-11 23:33:13 - Calculator] Failed to install Calculator.apk on device 'emulator-5554': device not found
[2011-11-11 23:33:13 - Calculator] com.android.ddmlib.InstallException: device not found
[2011-11-11 23:33:13 - Calculator] Launch canceled!

[2011-11-14 11:41:05 - Calculator1.0] emulator-5554 disconnected! Cancelling 'com.calculator.CalculatorActivity activity launch'!
[2011-11-14 11:48:22 - Calculator1.0] Failed to install Calculator1.0.apk on device 'emulator-5554!
[2011-11-14 11:48:22 - Calculator1.0] (null)
[2011-11-14 11:48:22 - Calculator1.0] Failed to install Calculator1.0.apk on device 'emulator-5554': EOF
[2011-11-14 11:48:22 - Calculator1.0] com.android.ddmlib.InstallException: EOF
[2011-11-14 11:48:22 - Calculator1.0] Launch canceled!

These issues were fixed by trying to run the application again. However the behavior of the application continued to be erratic.

Finally I started using the following procedure. In case I did not have the emulator running; I started it by running the Hello World application of my previous blog post. After it was successfully running, I ran my new Calculator application in the already started emulator. It has consistently run fine. Here’s the expected console output:

[2011-11-16 18:21:40 - Calculator1.0] Android Launch!
[2011-11-16 18:21:40 - Calculator1.0] adb is running normally.
[2011-11-16 18:21:40 - Calculator1.0] Performing com.calculator.CalculatorActivity activity launch
[2011-11-16 18:21:45 - Calculator1.0] Uploading Calculator1.0.apk onto device 'emulator-5554'
[2011-11-16 18:21:45 - Calculator1.0] Installing Calculator1.0.apk...
[2011-11-16 18:21:52 - Calculator1.0] Success!
[2011-11-16 18:21:52 - Calculator1.0] Starting activity com.calculator.CalculatorActivity on device emulator-5554
[2011-11-16 18:21:53 - Calculator1.0] ActivityManager: Starting: Intent { act=android.intent.action.MAIN cat=[android.intent.category.LAUNCHER] cmp=com.calculator/.CalculatorActivity }

This approach has been useful for debugging as well. I was trying to run the Calculator application independently and it was unable to run on the emulator. I had by oversight placed the onClick attribute in the Spinner instead of the Button. This was causing the application to fail. To add to my woes the LogCat was showing nothing giving me no idea as to the reason for the error. I used my new approach of having Hello World app to get my emulator up and running. Next I ran the Calculator application, the exception trace immediately appeared in LogCat allowing me to easily debug the problem.

That’s all for the moment. In the next blog post I will try to skim below the Android layout surface.

• Operating System: Windows 7
• Java Version: Java 1.6.0_24
• Eclipse environment: Eclipse Java EE IDE for Web Developers – Indigo Service Release 1 (3.7.1)
• Android SDK: Android 4.0
• Eclipse Plugin: ADT (Android Development Tools) Eclipse Plugin 15.0.0

Installation and Configuration

Java is presumed to be already installed. Install the Eclipse environment. Download the eclipse installable. Eclipse ‘Classic’ version is satisfactory, however I am using Jave EE IDE for Web Developers version. Any Eclipse version greater than 3.5 is suitable.

Next proceed to installing the Android SDK. Download the SDK starter package. Run the starter package. On completion of the installation of starter package, run the SDK Mananger executable. The wizard will prompt the user to select Android packages to install. Select the following under Android 4.0 (API14):

• Documentation
• SDK Platform
• Samples for SDK
• ARM EABI v7a System Image (This is required for Android Virtual Device)
• Google APIs (optional)

In Tools select the following:

• Android SDK Tools
• Android SDK Platform-Tools

For more details on recommended Andriod platform components for installation refer here.

Next, let’s install the Android Development Tools(ADT) eclipse plugin. I tried installing using the update site (both HTTPs and HTTP) but was unsuccessful; so I used the direct download option. For configuring the ADT plugin, refer the instructions mentioned here.

The official installation guide for Android can be found here.

This completes the installation and configuration of the Android platform and ADT plugin on Eclipse platform. Now let’s move on to our first working example Hello World.

Hello World Application/App

To create the Hello World Android project, start Eclipse, then select File -> New -> Other -> Android Project. Enter project name as HelloWorld, select Android 4.0 as build target and com.android.hello as package name. Leave the default selections for Create Activity and Minimum SDK. The HelloWorld project will be created in the eclipse environment. In the created project’s folder structure note two folders namely src and res. The src will have the class com.android.hello.HelloWorldActivity. Open the class. The class extends Activity class. Activity class is responsible for creating the window in which the developer places his/her custom UI contents. Here’s the source code of the HelloWorldActivity class. Note the implementation of onCreate method has been customized. The default implementation will be different.

package com.android.hello;

import android.app.Activity;
import android.os.Bundle;
import android.widget.TextView;

public class HelloWorldActivity extends Activity {
    
	/** Called when the activity is first created. */
    @Override
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        TextView view = new TextView(this);
        view.setText("This is my introduction to the world of Andriod.");
        setContentView(view);
    }
}

As the method name suggests the onCreate method is invoked during the creation of the Activity instance. Note the following three lines of the onCreate method implementation.

        TextView view = new TextView(this);
        view.setText("This is my introduction to the world of Andriod.");
        setContentView(view);

The first line creates the Android UI widget TextView which is used for displaying textual content. The second line assigns the text content i.e. ‘This is my introduction to the world of Andriod.’ and the third associates the TextView to the Activity instance.

In the eclipse package explorer examine the res folder. This folder will have two sub folders namely layout and values. The main.xml within layout folder’s use will be elaborated in Part 2 of this series. The strings.xml in values folder holds the message resources in a typical key value pair fashion. The application name is stored under the key app_name. Currently the value is defaulted to the Android project name; you are free to customize.

Now let’s run the Hello World Android application. To run the application we need an Android device or something that emulates an Android device. The ADT plugin provides an Android Virtual Device(AVD) emulator. The AVD can be created by invoking AVD Manager.exe directly within the Android SDK or within the Eclipse environment using the menu Window -> AVD Manager. For instructions on creating AVD refer here. While configuring the AVD, for skin select the built-in HVGA. This helps in reducing the start-up time, in turn improving the developer productivity.

Errors & their fixes while running the Hello World Application

In case one has installed the SDK in the non-standard location like D: drive etc you might encounter the following error.

[2011-11-11 12:34:18 - Emulator] PANIC: Could not open: C:\Users\<username>\.android/avd/myAVD.ini 

One of the ways to fix this problem is to copy the contents on the .android folder to the C:\Users\ folder. The other is run the following command:

mklink /J "C:\Users\<username>\.android" "D:\Users\<username>\.android"

Note the mklink command only works in Vista and Windows 7 operating systems.

The other problem experienced by developers is the following:

Unable to find a 'userdata.img' file for ABI armeabi to copy into the AVD folder.

This error is experienced if the package ‘ARM EABI v7a System Image’ is not installed in the SDK. Install it and the error should go away.

Now to run the app, right click on the HelloWorld project in the package explorer. Select Run As -> Android Application. The Run configuration wizard is displayed. Retain the defaults and select the Automatic option for target. The eclipse console will show the following if the deployment is successful:

[2011-11-15 14:29:01 - HelloWorld] ------------------------------
[2011-11-15 14:29:01 - HelloWorld] Android Launch!
[2011-11-15 14:29:01 - HelloWorld] adb is running normally.
[2011-11-15 14:29:01 - HelloWorld] Performing com.android.hello.HelloWorldActivity activity launch
[2011-11-15 14:29:01 - HelloWorld] Automatic Target Mode: launching new emulator with compatible AVD 'myAVD'
[2011-11-15 14:29:01 - HelloWorld] Launching a new emulator with Virtual Device 'myAVD'
[2011-11-15 14:29:24 - HelloWorld] New emulator found: emulator-5554
[2011-11-15 14:29:24 - HelloWorld] Waiting for HOME ('android.process.acore') to be launched...
[2011-11-15 14:30:42 - HelloWorld] HOME is up on device 'emulator-5554'
[2011-11-15 14:30:42 - HelloWorld] Uploading HelloWorld.apk onto device 'emulator-5554'
[2011-11-15 14:30:43 - HelloWorld] Installing HelloWorld.apk...
[2011-11-15 14:31:42 - HelloWorld] Success!
[2011-11-15 14:31:42 - HelloWorld] Starting activity com.android.hello.HelloWorldActivity on device emulator-5554
[2011-11-15 14:31:44 - HelloWorld] ActivityManager: Starting: Intent { act=android.intent.action.MAIN cat=[android.intent.category.LAUNCHER] cmp=com.android.hello/.HelloWorldActivity }

Note the considerable time spent between the Waiting for HOME and HOME is up on device…. statements. This is primarily because the Android architecture is defined on a different CPU vis-a-vis the Intel or AMD processor architecture. Therefore the emulator takes time to compile code.

Note that once the AVD has been started it should not be shutdown, you can run the application on the started AVD instance. To achieve this in the Run configuration set the target selection in manual mode. The user will be prompted to select the target AVD. On being prompted select the newly started AVD. For details check reference and read answer from ‘spiffly’.

The AVD should open the application with the App name ‘HelloWorld’ and the text as mentioned in the onCreate method prominently displayed on the emulator screen.

That’s all for android development desk. In my next blog post I will create a small working Android application.

First, I need to setup a service provider which will serve me consumable RESTful Web Services. I selected RESTful Web Services API provided by geonames.org. The site provides detailed documentation(http://www.geonames.org/export/web-services.html) along with sample URLs for consumption. The sample URLs are:

http://api.geonames.org/postalCodeSearch?postalcode=24501&maxRows=10&username=demo
http://api.geonames.org/postalCodeSearchJSON?postalcode=9011&maxRows=10&username=demo

I have used the demo user. This user has a daily user limit. So I suggest you create your own user. GeoNames offers free services for a defined daily limit. It also provides it’s own client libraries; for the purpose of this tutorial I have chosen to ignore these libraries. The Geonames API supports message payload delivery in XML and JSON format. We will have a look at both types of payload. First let’s look at XML payload.

Here’s the sample URL for XML payload. I am searching for postal code 24501 with a limit of retrieving max. 10 results.

http://api.geonames.org/postalCodeSearch?postalcode=24501&maxRows=10&username=demo

The XML payload is as below:

<geonames>
	<totalResultsCount>4</totalResultsCount>
	<code>
		<postalcode>24501</postalcode>
		<name>Lynchburg</name>
		<countryCode>US</countryCode>
		<lat>37.38311</lat>
		<lng>-79.17833</lng>
		<adminCode1>VA</adminCode1>
		<adminName1>Virginia</adminName1>
		<adminCode2>680</adminCode2>
		<adminName2>Lynchburg (city)</adminName2>
		<adminCode3/><adminName3/>
	</code>
	<code>
		<postalcode>24501</postalcode>
		<name>Rasoolabad</name>
		<countryCode>PK</countryCode>
		<lat>34.18583</lat>
		<lng>71.76333</lng>
		<adminCode1/>
		<adminName1>NWFP Peshawar</adminName1>
		<adminCode2/><adminName2/>
		<adminCode3/><adminName3/>
	</code>
	<code>
		<postalcode>24501</postalcode>
		<name>Chitral Karoona</name>
		<countryCode>PK</countryCode>
		<lat>34.18583</lat>
		<lng>71.76333</lng>
		<adminCode1/>
		<adminName1>NWFP Peshawar</adminName1>
		<adminCode2/><adminName2/>
		<adminCode3/><adminName3/>
	</code>
	<code>
		<postalcode>24501</postalcode>
		<name>Staffanstorp</name>
		<countryCode>SE</countryCode>
		<lat>55.64277</lat>
		<lng>13.20638</lng>
		<adminCode1>M</adminCode1>
		<adminName1>Skåne</adminName1>
		<adminCode2>1230</adminCode2>
		<adminName2>Staffanstorp</adminName2>
		<adminCode3/>
		<adminName3/>
	</code>
</geonames>

The RESTEasy framework is a Java based framework. Therefore, the developer will be interested in working with POJOs (Plain Old Java Object) and not raw XML. The RESTEasy framework facilitates this by using built-in JAXB (Java API for XML Binding) features. To match the XML payload structure I am creating two Java classes GeoNames and GeoCode. The source code of the two classes is shown below:

package com.resteasy.model;

import java.util.ArrayList;

import javax.xml.bind.annotation.XmlElement;
import javax.xml.bind.annotation.XmlRootElement;

@XmlRootElement(name="geonames")
public class GeoNames {
	
	private int resultsCount = 0;
	private ArrayList<GeoCode> codes = new ArrayList<GeoCode>();
	
	@XmlElement(name="totalResultsCount")
	public int getResultsCount() {
		return resultsCount;
	}
	public void setResultsCount(int resultsCount) {
		this.resultsCount = resultsCount;
	}
	
	@XmlElement(name="code")
	public ArrayList<GeoCode> getCodes() {
		return this.codes;
	}
	public void setCode(ArrayList<GeoCode> codes) {
		this.codes = codes;
	}
	
	@Override 
	public String toString() {
		StringBuilder sb = new StringBuilder();
		sb.append("Names....");
		sb.append("\n");
		sb.append("Results Count: ");
		sb.append(this.resultsCount);
		sb.append("\n");
		for (GeoCode code : this.codes) {
			sb.append("**********\n");
			sb.append(code);
			sb.append("**********\n");
		}
		
		return sb.toString();
	}	
}

package com.resteasy.model;

import java.math.BigDecimal;

import javax.xml.bind.annotation.XmlElement;
import javax.xml.bind.annotation.XmlRootElement;

import org.codehaus.jackson.annotate.JsonProperty;

@XmlRootElement (name="code")
public class GeoCode {
	
	private int postalCode = 0;
	private String name = null;
	private String countryCode = null;
	private BigDecimal latitude = null;
	private BigDecimal longitude = null;
	private String adminCode1 = null;
	private String adminName1 = null;
	private String adminCode2 = null;
	private String adminName2 = null;
	private String adminCode3 = null;
	private String adminName3 = null;

	@XmlElement (name="postalcode")
	public int getPostalCode() {
		return postalCode;
	}
	public void setPostalCode(int postalCode) {
		this.postalCode = postalCode;
	}
	
	@XmlElement (name="name")
	public String getName() {
		return name;
	}
	
	@JsonProperty("placeName")
	public void setName(String name) {
		this.name = name;
	}
	
	@XmlElement (name="countryCode")
	public String getCountryCode() {
		return countryCode;
	}
	public void setCountryCode(String countryCode) {
		this.countryCode = countryCode;
	}
	
	@XmlElement (name="lat")
	public BigDecimal getLatitude() {
		return latitude;
	}
	
	@JsonProperty("lat")
	public void setLatitude(BigDecimal latitude) {
		this.latitude = latitude;
	}
	
	@XmlElement (name="lng")
	public BigDecimal getLongitude() {
		return longitude;
	}
	@JsonProperty("lng")
	public void setLongitude(BigDecimal longitude) {
		this.longitude = longitude;
	}
	
	@XmlElement (name="adminCode1")
	public String getAdminCode1() {
		return adminCode1;
	}
	public void setAdminCode1(String adminCode1) {
		this.adminCode1 = adminCode1;
	}
	
	@XmlElement (name="adminName1")
	public String getAdminName1() {
		return adminName1;
	}
	public void setAdminName1(String adminName1) {
		this.adminName1 = adminName1;
	}
	
	@XmlElement (name="adminCode2")
	public String getAdminCode2() {
		return adminCode2;
	}
	public void setAdminCode2(String adminCode2) {
		this.adminCode2 = adminCode2;
	}
	
	@XmlElement (name="adminName2")
	public String getAdminName2() {
		return adminName2;
	}
	public void setAdminName2(String adminName2) {
		this.adminName2 = adminName2;
	}
	
	@XmlElement (name="adminCode3")
	public String getAdminCode3() {
		return adminCode3;
	}
	public void setAdminCode3(String adminCode3) {
		this.adminCode3 = adminCode3;
	}
	
	@XmlElement (name="adminName3")
	public String getAdminName3() {
		return adminName3;
	}
	public void setAdminName3(String adminName3) {
		this.adminName3 = adminName3;
	}

	@Override
	public String toString() {
		StringBuilder sb = new StringBuilder();
		sb.append("PostalCode: ");
		sb.append(this.postalCode);
		sb.append("\n");
		sb.append("Name: ");
		sb.append(this.name);
		sb.append("\n");
		sb.append("Country Code: ");
		sb.append(this.countryCode);
		sb.append("\n");
		sb.append("Latitude: ");
		sb.append(this.latitude);
		sb.append("\n");
		sb.append("Longitude: ");
		sb.append(this.longitude);
		sb.append("\n");
		sb.append("Admin Name 1: ");
		sb.append(this.adminName1);
		sb.append("\n");
		sb.append("Admin Code 1: ");
		sb.append(this.adminCode1);
		sb.append("\n");
		sb.append("Admin Name 2: ");
		sb.append(this.adminName2);
		sb.append("\n");
		sb.append("Admin Code 2: ");
		sb.append(this.adminCode2);
		sb.append("\n");
		sb.append("Admin Name 3: ");
		sb.append(this.adminName3);
		sb.append("\n");
		sb.append("Admin Code 3: ");
		sb.append(this.adminCode1);
		sb.append("\n");

		return sb.toString();
	}	
}

I have used annotations to achieve XML binding between the payload and Java classes. Detailed explanation of the JAXB annotation is outside the purview of this blog post. However the annotation names are self-explanatory. There are some JSON annotations in GeoCode, however our current focus is only on XML annotations i.e. annotations whose names are prefixed by “Xml”. In case there is a difference between the XML element and Class property use the name variable in the XMLElement annotation to map the XML element name to the class property. For e.g. refer the following annotation for latitude property in GeoCode class.

	@XmlElement (name="lat")
	public BigDecimal getLatitude() {
		return latitude;
	}

The next step is to create an interface which will act as a Proxy for communicating with the Geonames API. Here’s the source code of the proxy GeoNamesService. RESTful Web Services specific annotations are used. For explanation refer to my previous blog post of RESTful Web Services.

package com.resteasy.client;

import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;
import javax.ws.rs.QueryParam;

import org.jboss.resteasy.client.ClientResponse;

import com.resteasy.model.GeoNames;
import com.resteasy.model.PostalCodesJSON;

@Path("")
public interface GeoNamesService {

	@GET
	@Produces("application/xml")
	ClientResponse<GeoNames> getPostalCodeInformation(@QueryParam("postalcode") int postalCode,
			@QueryParam("maxRows") int rows, @QueryParam("username") String userName);

	@GET
	@Produces("application/xml")
	ClientResponse<GeoNames> getPostalCodes();

	@GET
	@Produces("application/json")
	ClientResponse<PostalCodesJSON> getPostalCodesinJSON(@QueryParam("postalcode") int postalCode,
			@QueryParam("maxRows") int rows, @QueryParam("username") String userName);
	
}

I have defined three methods, a parameterized getPostalCodeInformation, getPostalCodes and getPostalCodesinJSON. The first two handle XML payload and the last one is for JSON. Let’s focus on the first two. The methods are expected to return the ClientResponse class with a type variable aligned to the XML payload. Therefore for the XML payload we have defined the type as GeoNames, a class whose structure has been aligned to the XML structure. The second method getPostalCodes does not accept any argument.

	@GET
	@Produces("application/xml")
	ClientResponse<GeoNames> getPostalCodes();

Update(2nd Jan 2012):The following libraries have been included in the classpath for RESTfulWSClientJSON:

• commons-codec-1.2.jar
• commons-httpclient-3.1.jar
• commons-logging-1.0.4.jar
• jackson-core-asl-1.6.3.jar
• jackson-jaxrs-1.6.3.jar
• jackson-mapper-asl-1.6.3.jar
• resteasy-jackson-provider-2.2.2.GA.jar
• resteasy-jaxrs-2.2.2.GA.jar
• jaxrs-api-2.2.2.GA.jar

The following libraries are needed for the other two test classes.

• commons-codec-1.2.jar
• commons-httpclient-3.1.jar
• commons-logging-1.0.4.jar
• resteasy-jaxrs-2.2.2.GA.jar
• jaxrs-api-2.2.2.GA.jar
• jaxb-impl-2.2.4.jar
• resteasy-jaxb-provider-2.2.2.GA.jar

Please note that GeoCode is a shared class for all the clients. Therefore comment out the JsonProperty related code when using these two client classes.

End Update
Now let’s take it for a test run. Here’s the source code of the test class RESTFulWSClientNoParam.

package com.resteasy.client;

import org.jboss.resteasy.client.ClientResponse;
import org.jboss.resteasy.client.ProxyFactory;

import com.resteasy.model.GeoNames;

public class RESTFulWSClientNoParam {

	private static final String GEONAMES_URL = "http://api.geonames.org/postalCodeSearch?" +
			"postalcode=24501&maxRows=10&username=demo";
		
	public static void main(String[] args) {
		
		GeoNamesService service = ProxyFactory.create(GeoNamesService.class, GEONAMES_URL);
		ClientResponse<GeoNames> response = service.getPostalCodes();
		
		if (response.getStatus() == 200 ) {
			GeoNames names = response.getEntity();
			System.out.println(names);
			
		} else {
			System.out.println("Request processing failed. HTTP Status: " +        response.getStatus()
			+ " " + response.toString());
		}
		response.releaseConnection();

	}
}

The test class run output is

Names....
Results Count: 4
**********
PostalCode: 24501
Name: Lynchburg
Country Code: US
Latitude: 37.38311
Longitude: -79.17833
Admin Name 1: Virginia
Admin Code 1: VA
Admin Name 2: Lynchburg (city)
Admin Code 2: 680
Admin Name 3: 
Admin Code 3: VA
**********
**********
PostalCode: 24501
Name: Rasoolabad
Country Code: PK
Latitude: 34.18583
Longitude: 71.76333
Admin Name 1: NWFP Peshawar
Admin Code 1: 
Admin Name 2: 
Admin Code 2: 
Admin Name 3: 
Admin Code 3: 
**********
**********
PostalCode: 24501
Name: Chitral Karoona
Country Code: PK
Latitude: 34.18583
Longitude: 71.76333
Admin Name 1: NWFP Peshawar
Admin Code 1: 
Admin Name 2: 
Admin Code 2: 
Admin Name 3: 
Admin Code 3: 
**********
**********
PostalCode: 24501
Name: Staffanstorp
Country Code: SE
Latitude: 55.64277
Longitude: 13.20638
Admin Name 1: Skåne
Admin Code 1: M
Admin Name 2: Staffanstorp
Admin Code 2: 1230
Admin Name 3: 
Admin Code 3: M
**********

The RESTful Web Services client class ProxyFactory creates the GeoNamesService interface implementation proxy using the create method. The method takes two arguments, one is the Client Proxy class and second is the string URL of the RESTful Web Service. The ClientResponse class provides getStatus method which maps to HTTP status code. The rest of the code is self-explanatory.

As we are using the complete URL including the query parameter the Path annotation (line number 13) in the client proxy interface GeoNamesService is provided a value “” instead of the usual “/”.

Typically RESTful Web Services API accept arguments. To illustrate parameterized RESTful Web Service APIs look at the method getPostalCodeInformation in GeoNamesService interface.

	@GET
	@Produces("application/xml")
	ClientResponse<GeoNames> getPostalCodeInformation(@QueryParam("postalcode") int postalCode,
			@QueryParam("maxRows") int rows, @QueryParam("username") String userName);

The method getPostalCodeInformation accepts three arguments namely postal code, max. rows and user name. Here’s the test class RESTFulWSClient.

package com.resteasy.client;

import org.jboss.resteasy.client.ClientResponse;
import org.jboss.resteasy.client.ProxyFactory;

import com.resteasy.model.GeoNames;

public class RESTFulWSClient {

	private static final String GEONAMES_URL = "http://api.geonames.org/postalCodeSearch";
		
	public static void main(String[] args) {
		
		GeoNamesService service = ProxyFactory.create(GeoNamesService.class, GEONAMES_URL);
		ClientResponse<GeoNames> response = service.getPostalCodeInformation(24501, 10, "demo");
		
		if (response.getStatus() == 200 ) {
			GeoNames names = response.getEntity();
			System.out.println(names);
		} else {
			System.out.println("Request processing failed. HTTP Status: " + response.getStatus()
			+ " " + response.getLocation());
		}
		response.releaseConnection();

	}
}

The output of the test class is similar to the earlier output.

So far we have covered the XML payload RESTEasy Client processing. Let’s have a look at the JSON option.
Here’s the JSON URL:

http://api.geonames.org/postalCodeSearchJSON?postalcode=24501&maxRows=10&username=demo

Here’s the JSON output:

{"postalCodes":[{"adminName2":"Lynchburg (city)","adminCode2":"680","adminCode1":"VA","postalCode":"24501","countryCode":"US",
"lng":-79.178326,"placeName":"Lynchburg","lat":37.383112,"adminName1":"Virginia"},{"postalCode":"24501","countryCode":"PK","lng":71.7633333,"placeName":"Rasoolabad","lat":34.1858333,
"adminName1":"NWFP Peshawar"},{"postalCode":"24501","countryCode":"PK","lng":71.7633333,"placeName":"Chitral Karoona","lat":34.1858333,"adminName1":"NWFP Peshawar"},{"adminName2":"Staffanstorp","adminCode2":"1230","adminCode1":"M","postalCode":"24501",
"countryCode":"SE","lng":13.206381797790527,"placeName":"Staffanstorp","lat":55.642772521210716,
"adminName1":"Skåne"}]}

The structure of the JSON payload is slightly different from the XML payload. Therefore I have defined a new Class PostalCodesJSON. This class continues to reuse GeoCode class.

package com.resteasy.client;

import org.jboss.resteasy.client.ClientResponse;
import org.jboss.resteasy.client.ProxyFactory;

import com.resteasy.model.PostalCodesJSON;


public class RESTFulWSClientJSON {

	private static final String GEONAMES_URL = "http://api.geonames.org/postalCodeSearchJSON";
		
	public static void main(String[] args) {
		
		GeoNamesService service = ProxyFactory.create(GeoNamesService.class, GEONAMES_URL);
		ClientResponse<PostalCodesJSON> response = service.getPostalCodesinJSON(24501, 10, "demo");
		
		if (response.getStatus() == 200 ) {
			PostalCodesJSON codes = response.getEntity();
			System.out.println(codes);
		} else {
			System.out.println("Request processing failed. HTTP Status: " + response.getStatus()
			+ " " + response.getLocation());
		}
		response.releaseConnection();

	}

}

Note that we have defined GeoCode as a List in the PostalCodesJSON class. They can also be defined as a GeoCode array. The rest of the code remains unchanged.

Refer to the third method defined in getPostalCodesinJSON. It accepts three arguments similar to the getPostalCodeInformation method.

	@GET
	@Produces("application/json")
	ClientResponse<PostalCodesJSON> getPostalCodesinJSON(@QueryParam("postalcode") int postalCode,
			@QueryParam("maxRows") int rows, @QueryParam("username") String userName);

In case there are differences in the JSON property name and corresponding Class property name, use the JsonProperty annotation to map the JSON property to class property. For example, refer latitude property in GeoCode class.

	@JsonProperty("lat")
	public void setLatitude(BigDecimal latitude) {
		this.latitude = latitude;
	}

There is a reason why the JsonProperty annotation is defined on the setLatitude method. As a consuming application, we are deserializing from JSON format to POJO property. This process invokes the setter method. In case of serialization the JsonProperty would have to be defined in the getLatitude method.

Here’s the test class RESTFulWSClientJSON for JSON payload.

package com.resteasy.client;

import org.jboss.resteasy.client.ClientResponse;
import org.jboss.resteasy.client.ProxyFactory;

import com.resteasy.model.PostalCodesJSON;


public class RESTFulWSClientJSON {

	private static final String GEONAMES_URL = "http://api.geonames.org/postalCodeSearchJSON";
		
	public static void main(String[] args) {
		
		GeoNamesService service = ProxyFactory.create(GeoNamesService.class, GEONAMES_URL);
		ClientResponse<PostalCodesJSON> response = service.getPostalCodesinJSON(24501, 10, "demo");
		
		if (response.getStatus() == 200 ) {
			PostalCodesJSON codes = response.getEntity();
			System.out.println(codes);
		} else {
			System.out.println("Request processing failed. HTTP Status: " + response.getStatus()
			+ " " + response.getLocation());
		}
		response.releaseConnection();

	}
}

Here’s the test class run output:

Names....

**********
PostalCode: 24501
Name: Lynchburg
Country Code: US
Latitude: 37.383112
Longitude: -79.178326
Admin Name 1: Virginia
Admin Code 1: VA
Admin Name 2: Lynchburg (city)
Admin Code 2: 680
Admin Name 3: null
Admin Code 3: VA
**********
**********
PostalCode: 24501
Name: Rasoolabad
Country Code: PK
Latitude: 34.1858333
Longitude: 71.7633333
Admin Name 1: NWFP Peshawar
Admin Code 1: null
Admin Name 2: null
Admin Code 2: null
Admin Name 3: null
Admin Code 3: null
**********
**********
PostalCode: 24501
Name: Chitral Karoona
Country Code: PK
Latitude: 34.1858333
Longitude: 71.7633333
Admin Name 1: NWFP Peshawar
Admin Code 1: null
Admin Name 2: null
Admin Code 2: null
Admin Name 3: null
Admin Code 3: null
**********
**********
PostalCode: 24501
Name: Staffanstorp
Country Code: SE
Latitude: 55.642772521210716
Longitude: 13.206381797790527
Admin Name 1: Skåne
Admin Code 1: M
Admin Name 2: Staffanstorp
Admin Code 2: 1230
Admin Name 3: null
Admin Code 3: M
**********

That covers the RESTEasy Client Framework tutorial.

Before getting into the nitty gritties of hibernate fetch, a quick summary of the setup. I am using the following softwares:

• Hibernate 3.6.6
• Oracle Express Edition 10.2.0.1.0
• Eclipse 3.4.1
• Windows 7 Operating System

Now let’s move on to hibernate configuration. First the hibernate configuration xml i.e. hibernate.cfg.xml.

<?xml version='1.0' encoding='utf-8'?>
<!DOCTYPE hibernate-configuration PUBLIC
        "-//Hibernate/Hibernate Configuration DTD 3.0//EN"
        "http://www.hibernate.org/dtd/hibernate-configuration-3.0.dtd">

<hibernate-configuration>

    <session-factory>

        <!-- Database connection settings -->
        <property name="connection.driver_class">oracle.jdbc.driver.OracleDriver</property>
        <property name="connection.url">jdbc:oracle:thin:@localhost:1521:xe</property>
        <property name="connection.username">system</property>
        <property name="connection.password">manager</property>

        <!-- JDBC connection pool (use the built-in) -->
        <property name="connection.pool_size">10</property>

        <!-- SQL dialect -->
        <property name="dialect">org.hibernate.dialect.Oracle10gDialect</property>

        <!-- Enable Hibernate's automatic session context management -->
        <property name="current_session_context_class">thread</property>

        <!-- Disable the second-level cache  -->
        <property name="cache.provider_class">org.hibernate.cache.NoCacheProvider</property>

        <!-- Echo all executed SQL to stdout -->
        <property name="show_sql">true</property>
        <!--<property name="format_sql">true</property>-->
		<!--<property name="use_sql_comments">true</property>-->
        

        <!-- Drop and re-create the database schema on startup -->
        <property name="hbm2ddl.auto">update</property>

    </session-factory>

</hibernate-configuration>

I have defined the Oracle database details such as its driver class, connection URL, and credentials. Please customize these values to your environment specifics. Next we look at project dependencies. They are as follows:

• hibernate3.jar
• antlr-2.7.6.jar
• commons-collections-3.1.jar
• dom4j-1.6.1.jar
• hibernate-jpa-2.0-api-1.0.1.Final.jar
• javassist-3.12.0.GA.jar
• jta-1.1.jar
• log4j-1.2.16.jar
• ojdbc14.jar
• slf4j-api-1.6.1.jar
• slf4j-lo4j12-1.6.1.jar

Since we are using lo4j for logging, here’s the log4j properties file. Note specific changes have been made in the logging levels to gain insights into the SQL statements executed by hibernate. Refer lines 22 to 28. This is an essential tool for SQL debugging.

### direct log messages to stdout ###
log4j.appender.stdout=org.apache.log4j.ConsoleAppender
log4j.appender.stdout.Target=System.out
log4j.appender.stdout.layout=org.apache.log4j.PatternLayout
log4j.appender.stdout.layout.ConversionPattern=%d{ABSOLUTE} %5p %c{1}:%L - %m%n
### direct messages to file hibernate.log ###
log4j.appender.file=org.apache.log4j.FileAppender
log4j.appender.file.File=d:\hibernate.log
log4j.appender.file.layout=org.apache.log4j.PatternLayout
log4j.appender.file.layout.ConversionPattern=%d{ABSOLUTE} %5p %c{1}:%L - %m%n

### set log levels - for more verbose logging change 'debug' to 'debug' ##

log4j.rootLogger=info, file
#log4j.logger.net.sf.hibernate=debug

### enable the following line if you want to track down connection ###
### leakages when using DriverManagerConnectionProvider ###
#log4j.logger.net.sf.hibernate.connection.DriverManagerConnectionProvider=trace

### log JDBC bind parameters ###
log4j.logger.org.hibernate.SQL=DEBUG
log4j.logger.org.hibernate.type=TRACE
log4j.logger.org.hibernate.hql.ast.AST=info
log4j.logger.org.hibernate.tool.hbm2ddl=warn
log4j.logger.org.hibernate.hql=debug
log4j.logger.org.hibernate.cache=info
log4j.logger.org.hibernate.jdbc=debug

### log prepared statement cache activity ###
log4j.logger.org.hibernate.ps=debug

Now let’s move on to the meatier stuff of hibernate. To understand Hibernate’s fetch strategy let’s consider a scenario consisting of two entities Person and Address. They share a one-to-many relationship; i.e. one person has more than one addresses. Both the entities need to be made persistent.

I am using annotations to make the classes persistent. Here are the classes with their annotations.

package com.tutorial.hibernate.fetch;

import java.io.Serializable;
import java.util.ArrayList;
import java.util.List;

import javax.annotation.Generated;
import javax.persistence.CascadeType;
import javax.persistence.Column;
import javax.persistence.Entity;
import javax.persistence.Id;
import javax.persistence.OneToMany;
import javax.persistence.Table;

import org.hibernate.annotations.BatchSize;
import org.hibernate.annotations.Fetch;
import org.hibernate.annotations.FetchMode;

@Entity
@Table(name="PERSON",
		schema="SYSTEM")
public class Person implements Serializable {

	private static final long serialVersionUID = 4333499410830154895L;

	private int id = 0;
	private String firstName = null;
	private String lastName = null;

	private List<Address> addresses = new ArrayList<Address>();
	
	@Id
	@Generated(value="assigned")
	@Column(name="ID")
	public int getId() {
		return id;
	}

	public void setId(int id) {
		this.id = id;
	}

	@Column(name="FIRST_NAME")
	public String getFirstName() {
		return firstName;
	}

	public void setFirstName(String firstName) {
		this.firstName = firstName;
	}

	@Column(name="LAST_NAME")
	public String getLastName() {
		return lastName;
	}

	public void setLastName(String lastName) {
		this.lastName = lastName;
	}

	@OneToMany(mappedBy="person", cascade=CascadeType.ALL)
	@Column(name="id")
	@BatchSize(size=2)
	public List<Address> getAddresses() {
		return addresses;
	}

	public void setAddresses(List<Address> addresses) {
		this.addresses = addresses;
	}
	
	public void addAddress(Address address) {
		address.setPerson(this);
		this.addresses.add(address);
		
	}
	
	@Override
	public String toString() {
		StringBuilder sb = new StringBuilder();
		sb.append("**** Person **** ");
		sb.append("Id: ");
		sb.append(this.id);
		sb.append("\n");
		sb.append("First name: ");
		sb.append(this.firstName);
		sb.append("\n");
		sb.append("Last name: ");
		sb.append(this.lastName);
		sb.append("\n");
		sb.append("**** Person **** ");
		sb.append("\n");
		
		return sb.toString();
	}
	
}

package com.tutorial.hibernate.fetch;

import java.io.Serializable;

import javax.annotation.Generated;
import javax.persistence.Column;
import javax.persistence.Entity;
import javax.persistence.Id;
import javax.persistence.JoinColumn;
import javax.persistence.ManyToOne;
import javax.persistence.Table;

@Entity
@Table(name="ADDRESS",
		schema="SYSTEM")

public class Address implements Serializable {

	@Id
	@Generated(value="assigned")
	private int id = 0;
	
	@Column(name="FIRST_LINE")	
	private String firstLine  = null;
	@Column(name="SECOND_LINE")
	private String secondLine = null;
	@Column(name="CITY")
	private String city       = null;
	@Column(name="ZIP_CODE")
	private String zipCode    = null;
	@ManyToOne
	@JoinColumn(name="PERSON_ID")	
	private Person person     = null;
	
	@Column(name="PERSON_ID", insertable=false, updatable=false)
	private Integer personId = null;
	
	public int getId() {
		return id;
	}
	public void setId(int id) {
		this.id = id;
	}

	public String getFirstLine() {
		return firstLine;
	}
	
	public void setFirstLine(String firstLine) {
		this.firstLine = firstLine;
	}
	
	public String getSecondLine() {
		return secondLine;
	}
	
	public void setSecondLine(String secondLine) {
		this.secondLine = secondLine;
	}
	
	public String getCity() {
		return city;
	}
	
	public void setCity(String city) {
		this.city = city;
	}
	
	public String getZipCode() {
		return zipCode;
	}
	
	public void setZipCode(String zipCode) {
		this.zipCode = zipCode;
	}

	public Person getPerson() {
		return person;
	}
	
	public void setPerson(Person person) {
		this.person = person;
	}
	
	public Integer getPersonId() {
		return personId;
	}
	public void setPersonId(Integer personId) {
		this.personId = personId;
	}
	@Override
	public String toString() {
		StringBuilder sb = new StringBuilder();
		sb.append("***** Address ******");
		sb.append("\n");
		sb.append("Id: ");
		sb.append(this.id);
		sb.append("\n");
		sb.append("First Line: ");
		sb.append(this.firstLine);
		sb.append("\n");
		sb.append("Second Line: ");
		sb.append(this.secondLine);
		sb.append("\n");
		sb.append("City: ");
		sb.append(this.city);
		sb.append("\n");
		sb.append("Zip Code: ");
		sb.append(this.zipCode);
		sb.append("\n");
		sb.append("Person Id: ");
		sb.append(this.personId);
		sb.append("\n");
		sb.append("***** Address ******");
		sb.append("\n");
		
		return sb.toString();

	}
	
}

In the Person class refer the annotation defined for getAddresses method.

	@OneToMany(mappedBy="person", cascade=CascadeType.ALL)
	@Column(name="id")
	//@Fetch(FetchMode.SELECT)
	//@Fetch(FetchMode.SUBSELECT)
	//@BatchSize(size=2)

This annotation defines one-to-many relationship between Person and Address. Note the commented out lines for the Fetch and BatchSize annotation. This will be changed later as we progress.

Similarly a many-to-one relationship is defined in Address class for person attribute.

	@ManyToOne
	@JoinColumn(name="PERSON_ID")	
	private Person person     = null;

Purely from a relationship definition standpoint, there is no need to define the personId attribute in Address. This has been specifically added to facilitate querying using HQL. More on that later.

Run the following SQL scripts to create tables PERSON and ADDRESS in database.

CREATE TABLE person(id INTEGER, first_name VARCHAR2(20), last_name VARCHAR2(20), 
	PRIMARY KEY(id));
	
CREATE TABLE ADDRESS(id INTEGER, first_line VARCHAR2(20), second_line VARCHAR2(20), 
	city VARCHAR2(20), zip_code VARCHAR2(10), person_id INTEGER, 
	PRIMARY KEY(id), CONSTRAINT ADDRESS_FK1 FOREIGN KEY (person_id) REFERENCES person(id));

To query the database, we need to have data. The DataLoader class creates some records in PERSON and ADDRESS. On successful run of the code we will be creating two persons with four addresses each and one person with two addresses. Here’s the source code of DataLoader class.

package com.tutorial.hibernate.fetch;

import org.hibernate.Session;
import org.hibernate.SessionFactory;
import org.hibernate.Transaction;

public class DataLoader {

	public static void main(String[] args) {
		
		SessionFactory factory = HibernateUtil.getFactory();
		
		Session session = factory.openSession();
		Transaction tx = session.beginTransaction();
		Person p = new Person();
		p.setId(1);
		p.setFirstName("Bill");
		p.setLastName("Banks");
		
		Address a1 = new Address();
		a1.setFirstLine("Line 11");
		a1.setSecondLine("Line 12");
		a1.setZipCode("12345");
		a1.setId(1);
		a1.setPerson(p);
		p.addAddress(a1);
		
		Address a2 = new Address();
		a2.setFirstLine("Line 21");
		a2.setSecondLine("Line 22");
		a2.setZipCode("54321");
		a2.setId(2);
		a2.setPerson(p);
		p.addAddress(a2);

		Address a3 = new Address();
		a3.setFirstLine("Line 31");
		a3.setSecondLine("Line 32");
		a3.setZipCode("11221");
		a3.setId(3);
		a3.setPerson(p);
		p.addAddress(a3);

		Address a4 = new Address();
		a4.setFirstLine("Line 41");
		a4.setSecondLine("Line 42");
		a4.setZipCode("22331");
		a4.setId(4);
		a4.setPerson(p);
		p.addAddress(a4);

		Person p1 = new Person();
		p1.setId(2);
		p1.setFirstName("Steve");
		p1.setLastName("Jobs");
		
		Address a11 = new Address();
		a11.setFirstLine("Line 111");
		a11.setSecondLine("Line 112");
		a11.setZipCode("12345");
		a11.setId(5);
		a11.setPerson(p1);
		p1.addAddress(a11);
		
		Address a22 = new Address();
		a22.setFirstLine("Line 221");
		a22.setSecondLine("Line 222");
		a22.setZipCode("54321");
		a22.setId(6);
		a22.setPerson(p1);
		p1.addAddress(a22);

		Address a33 = new Address();
		a33.setFirstLine("Line 331");
		a33.setSecondLine("Line 332");
		a33.setZipCode("11221");
		a33.setId(7);
		a33.setPerson(p1);
		p1.addAddress(a33);

		Address a44 = new Address();
		a44.setFirstLine("Line 441");
		a44.setSecondLine("Line 442");
		a44.setZipCode("22331");
		a44.setId(8);
		a44.setPerson(p1);
		p1.addAddress(a44);

		Person p2 = new Person();
		p2.setId(3);
		p2.setFirstName("Clark");
		p2.setLastName("Jacob");
		
		Address a111 = new Address();
		a111.setFirstLine("Line 111");
		a111.setSecondLine("Line 112");
		a111.setZipCode("12345");
		a111.setId(9);
		a111.setPerson(p2);
		p2.addAddress(a111);
		
		Address a222 = new Address();
		a222.setFirstLine("Line 221");
		a222.setSecondLine("Line 222");
		a222.setZipCode("54321");
		a222.setId(10);
		a222.setPerson(p2);
		p2.addAddress(a222);
	
		session.save(p);
		session.save(p1);
		session.save(p2);
		
		tx.commit();
	}

}

On running the DataLoader class, the following SQL output is generated on the console:

Hibernate: select address_.id, address_.CITY as CITY1_, address_.FIRST_LINE as FIRST3_1_, address_.PERSON_ID as PERSON4_1_, address_.SECOND_LINE as SECOND5_1_, address_.ZIP_CODE as ZIP6_1_ from SYSTEM.ADDRESS address_ where address_.id=?
Hibernate: select address_.id, address_.CITY as CITY1_, address_.FIRST_LINE as FIRST3_1_, address_.PERSON_ID as PERSON4_1_, address_.SECOND_LINE as SECOND5_1_, address_.ZIP_CODE as ZIP6_1_ from SYSTEM.ADDRESS address_ where address_.id=?
Hibernate: select address_.id, address_.CITY as CITY1_, address_.FIRST_LINE as FIRST3_1_, address_.PERSON_ID as PERSON4_1_, address_.SECOND_LINE as SECOND5_1_, address_.ZIP_CODE as ZIP6_1_ from SYSTEM.ADDRESS address_ where address_.id=?
Hibernate: select address_.id, address_.CITY as CITY1_, address_.FIRST_LINE as FIRST3_1_, address_.PERSON_ID as PERSON4_1_, address_.SECOND_LINE as SECOND5_1_, address_.ZIP_CODE as ZIP6_1_ from SYSTEM.ADDRESS address_ where address_.id=?
Hibernate: select address_.id, address_.CITY as CITY1_, address_.FIRST_LINE as FIRST3_1_, address_.PERSON_ID as PERSON4_1_, address_.SECOND_LINE as SECOND5_1_, address_.ZIP_CODE as ZIP6_1_ from SYSTEM.ADDRESS address_ where address_.id=?
Hibernate: select address_.id, address_.CITY as CITY1_, address_.FIRST_LINE as FIRST3_1_, address_.PERSON_ID as PERSON4_1_, address_.SECOND_LINE as SECOND5_1_, address_.ZIP_CODE as ZIP6_1_ from SYSTEM.ADDRESS address_ where address_.id=?
Hibernate: select address_.id, address_.CITY as CITY1_, address_.FIRST_LINE as FIRST3_1_, address_.PERSON_ID as PERSON4_1_, address_.SECOND_LINE as SECOND5_1_, address_.ZIP_CODE as ZIP6_1_ from SYSTEM.ADDRESS address_ where address_.id=?
Hibernate: select address_.id, address_.CITY as CITY1_, address_.FIRST_LINE as FIRST3_1_, address_.PERSON_ID as PERSON4_1_, address_.SECOND_LINE as SECOND5_1_, address_.ZIP_CODE as ZIP6_1_ from SYSTEM.ADDRESS address_ where address_.id=?
Hibernate: select address_.id, address_.CITY as CITY1_, address_.FIRST_LINE as FIRST3_1_, address_.PERSON_ID as PERSON4_1_, address_.SECOND_LINE as SECOND5_1_, address_.ZIP_CODE as ZIP6_1_ from SYSTEM.ADDRESS address_ where address_.id=?
Hibernate: select address_.id, address_.CITY as CITY1_, address_.FIRST_LINE as FIRST3_1_, address_.PERSON_ID as PERSON4_1_, address_.SECOND_LINE as SECOND5_1_, address_.ZIP_CODE as ZIP6_1_ from SYSTEM.ADDRESS address_ where address_.id=?
Hibernate: insert into SYSTEM.PERSON (FIRST_NAME, LAST_NAME, ID) values (?, ?, ?)
Hibernate: insert into SYSTEM.ADDRESS (CITY, FIRST_LINE, PERSON_ID, SECOND_LINE, ZIP_CODE, id) values (?, ?, ?, ?, ?, ?)
Hibernate: insert into SYSTEM.ADDRESS (CITY, FIRST_LINE, PERSON_ID, SECOND_LINE, ZIP_CODE, id) values (?, ?, ?, ?, ?, ?)
Hibernate: insert into SYSTEM.ADDRESS (CITY, FIRST_LINE, PERSON_ID, SECOND_LINE, ZIP_CODE, id) values (?, ?, ?, ?, ?, ?)
Hibernate: insert into SYSTEM.ADDRESS (CITY, FIRST_LINE, PERSON_ID, SECOND_LINE, ZIP_CODE, id) values (?, ?, ?, ?, ?, ?)
Hibernate: insert into SYSTEM.PERSON (FIRST_NAME, LAST_NAME, ID) values (?, ?, ?)
Hibernate: insert into SYSTEM.ADDRESS (CITY, FIRST_LINE, PERSON_ID, SECOND_LINE, ZIP_CODE, id) values (?, ?, ?, ?, ?, ?)
Hibernate: insert into SYSTEM.ADDRESS (CITY, FIRST_LINE, PERSON_ID, SECOND_LINE, ZIP_CODE, id) values (?, ?, ?, ?, ?, ?)
Hibernate: insert into SYSTEM.ADDRESS (CITY, FIRST_LINE, PERSON_ID, SECOND_LINE, ZIP_CODE, id) values (?, ?, ?, ?, ?, ?)
Hibernate: insert into SYSTEM.ADDRESS (CITY, FIRST_LINE, PERSON_ID, SECOND_LINE, ZIP_CODE, id) values (?, ?, ?, ?, ?, ?)
Hibernate: insert into SYSTEM.PERSON (FIRST_NAME, LAST_NAME, ID) values (?, ?, ?)
Hibernate: insert into SYSTEM.ADDRESS (CITY, FIRST_LINE, PERSON_ID, SECOND_LINE, ZIP_CODE, id) values (?, ?, ?, ?, ?, ?)
Hibernate: insert into SYSTEM.ADDRESS (CITY, FIRST_LINE, PERSON_ID, SECOND_LINE, ZIP_CODE, id) values (?, ?, ?, ?, ?, ?)

Hibernate provides 4 strategies for retrieving data:

• SELECT
• JOIN
• SUBSELECT
• BATCH

Fetch Strategy : SELECT

At the moment the persistent classes are configured at default settings. Here’s the DataSelectFetch class to retrieve Person and Address records.

package com.tutorial.hibernate.fetch;

import java.util.List;

import org.hibernate.Query;
import org.hibernate.Session;
import org.hibernate.SessionFactory;

public class DataSelectFetch {

	public static void main(String[] args) {
		SessionFactory fact = HibernateUtil.getFactory();
		Session session = fact.openSession();
		
		Query q = session.createQuery(" FROM Person p ");
		
		System.out.println("Retrieving Data");
		List l = q.list();
		System.out.println("Data retrieved: " + l.size());
		for (Object object : l) {
			Person p = (Person) object;
			System.out.println(p);
			System.out.println("Address retrieval initiated.");
			List<Address> addresses = p.getAddresses();
			System.out.println("Address retrieval complete.");
			int i=1;
			for (Address address : addresses) {
				System.out.println("#### individual address: " + i);
				System.out.println(address);
				System.out.println("#### Address complete");
				i++;
			}
		}

	}
}

The console output generated is as below:

Retrieving Data
Hibernate: select person0_.ID as ID0_, person0_.FIRST_NAME as FIRST2_0_, person0_.LAST_NAME as LAST3_0_ from SYSTEM.PERSON person0_
Data retrieved: 3
**** Person **** Id: 1
First name: Bill
Last name: Banks
**** Person **** 

Address retrieval initiated.
Address retrieval complete.
Hibernate: select addresses0_.PERSON_ID as PERSON4_0_1_, addresses0_.id as id1_, addresses0_.id as id1_0_, addresses0_.CITY as CITY1_0_, addresses0_.FIRST_LINE as FIRST3_1_0_, addresses0_.PERSON_ID as PERSON4_1_0_, addresses0_.SECOND_LINE as SECOND5_1_0_, addresses0_.ZIP_CODE as ZIP6_1_0_ from SYSTEM.ADDRESS addresses0_ where addresses0_.PERSON_ID=?
#### individual address: 1
***** Address ******
Id: 1
First Line: Line 11
Second Line: Line 12
City: null
Zip Code: 12345
Person Id: 1
***** Address ******

#### Address complete
#### individual address: 2
***** Address ******
Id: 2
First Line: Line 21
Second Line: Line 22
City: null
Zip Code: 54321
Person Id: 1
***** Address ******

#### Address complete
#### individual address: 3
***** Address ******
Id: 3
First Line: Line 31
Second Line: Line 32
City: null
Zip Code: 11221
Person Id: 1
***** Address ******

#### Address complete
#### individual address: 4
***** Address ******
Id: 4
First Line: Line 41
Second Line: Line 42
City: null
Zip Code: 22331
Person Id: 1
***** Address ******

#### Address complete
**** Person **** Id: 2
First name: Steve
Last name: Jobs
**** Person **** 

Address retrieval initiated.
Address retrieval complete.
Hibernate: select addresses0_.PERSON_ID as PERSON4_0_1_, addresses0_.id as id1_, addresses0_.id as id1_0_, 
addresses0_.CITY as CITY1_0_, addresses0_.FIRST_LINE as FIRST3_1_0_, addresses0_.PERSON_ID as PERSON4_1_0_, addresses0_.SECOND_LINE as SECOND5_1_0_, addresses0_.ZIP_CODE as ZIP6_1_0_ from SYSTEM.ADDRESS addresses0_ where addresses0_.PERSON_ID=?
#### individual address: 1
***** Address ******
Id: 5
First Line: Line 111
Second Line: Line 112
City: null
Zip Code: 12345
Person Id: 2
***** Address ******

#### Address complete
#### individual address: 2
***** Address ******
Id: 6
First Line: Line 221
Second Line: Line 222
City: null
Zip Code: 54321
Person Id: 2
***** Address ******

#### Address complete
#### individual address: 3
***** Address ******
Id: 7
First Line: Line 331
Second Line: Line 332
City: null
Zip Code: 11221
Person Id: 2
***** Address ******

#### Address complete
#### individual address: 4
***** Address ******
Id: 8
First Line: Line 441
Second Line: Line 442
City: null
Zip Code: 22331
Person Id: 2
***** Address ******

#### Address complete
**** Person **** Id: 3
First name: Clark
Last name: Jacob
**** Person **** 

Address retrieval initiated.
Address retrieval complete.
Hibernate: select addresses0_.PERSON_ID as PERSON4_0_1_, addresses0_.id as id1_, addresses0_.id as id1_0_, 
addresses0_.CITY as CITY1_0_, addresses0_.FIRST_LINE as FIRST3_1_0_, addresses0_.PERSON_ID as PERSON4_1_0_, addresses0_.SECOND_LINE as SECOND5_1_0_, addresses0_.ZIP_CODE as ZIP6_1_0_ from SYSTEM.ADDRESS addresses0_ where addresses0_.PERSON_ID=?
#### individual address: 1
***** Address ******
Id: 9
First Line: Line 111
Second Line: Line 112
City: null
Zip Code: 12345
Person Id: 3
***** Address ******

#### Address complete
#### individual address: 2
***** Address ******
Id: 10
First Line: Line 221
Second Line: Line 222
City: null
Zip Code: 54321
Person Id: 3
***** Address ******

#### Address complete

There are four SQLs fired. This first one is fired for retrieving all the records in the PERSON table. The remaining three are fired for retrieving addresses records for each Person. This is basically the N+1 problem. The first query retrieves N records from database, in this case N Person records. For each Person a new query retrieves Addresses. Therefore for N persons, N queries retrieve information from ADDRESS table.

Change the annotation definition in the getAddresses method to the following:

	@OneToMany(mappedBy="person", cascade=CascadeType.ALL)
	@Column(name="id")
	@Fetch(FetchMode.SELECT)
	//@Fetch(FetchMode.SUBSELECT)
	//@BatchSize(size=2)

Basically uncomment the following line.

	@Fetch(FetchMode.SELECT)

Running DataSelectFetch generates the same console output. This is the SELECT fetch mode. Let’s now move on to the next fetch strategy join.

Fetch Strategy : JOIN

Refer to the class DataOuterJoinFetch.

package com.tutorial.hibernate.fetch;

import java.util.List;

import org.hibernate.Query;
import org.hibernate.Session;
import org.hibernate.SessionFactory;

public class DataOuterJoinFetch {

	public static void main(String[] args) {
		SessionFactory fact = HibernateUtil.getFactory();
		Session session = fact.openSession();
		
		Query q = session.createQuery(" SELECT p, a FROM Person as p left outer join p.addresses a where p.id = a.personId");
		
		System.out.println("Retrieving Data");
		List l = q.list();
		System.out.println("Result size: " + l.size());
		System.out.println("Data retrieved");
		for (Object object : l) {
			if (object instanceof Object[]) {
				Object[] objArr = (Object[]) object;
				System.out.println("Person");
				System.out.println(objArr[0]);
				System.out.println("Address");
				System.out.println(objArr[1]);
			} else {
				throw new RuntimeException("Unable to process.");
			}
		}

	}
}

Refer to line 15 of the source code. We have established an outer join between Person and Address. Note the usage of the personId attribute here. That is the reason to maintain the attribute. Also note the special attributes added in its annotation definition.

	@Column(name="PERSON_ID", insertable=false, updatable=false)
	private Integer personId = null;

The annotation definition ensures that many-to-one relationship maintains the PERSON_ID column value in the ADDRESS table. This attribute is purely for display purposes only.

The run output of DataOuterJoinFetch is as below:

Retrieving Data
Hibernate: select person0_.ID as ID0_0_, addresses1_.id as id1_1_, person0_.FIRST_NAME as FIRST2_0_0_, person0_.LAST_NAME as LAST3_0_0_, addresses1_.CITY as CITY1_1_, addresses1_.FIRST_LINE as FIRST3_1_1_, addresses1_.PERSON_ID as PERSON4_1_1_, addresses1_.SECOND_LINE as SECOND5_1_1_, addresses1_.ZIP_CODE as ZIP6_1_1_ from SYSTEM.PERSON person0_ left outer join SYSTEM.ADDRESS addresses1_ on person0_.ID=addresses1_.PERSON_ID where person0_.ID=addresses1_.PERSON_ID
Result size: 10
Data retrieved
Person
**** Person **** Id: 1
First name: Bill
Last name: Banks
**** Person **** 

Address
***** Address ******
Id: 1
First Line: Line 11
Second Line: Line 12
City: null
Zip Code: 12345
Person Id: 1
***** Address ******

Person
**** Person **** Id: 1
First name: Bill
Last name: Banks
**** Person **** 

Address
***** Address ******
Id: 2
First Line: Line 21
Second Line: Line 22
City: null
Zip Code: 54321
Person Id: 1
***** Address ******

Person
**** Person **** Id: 1
First name: Bill
Last name: Banks
**** Person **** 

Address
***** Address ******
Id: 3
First Line: Line 31
Second Line: Line 32
City: null
Zip Code: 11221
Person Id: 1
***** Address ******

Person
**** Person **** Id: 1
First name: Bill
Last name: Banks
**** Person **** 

Address
***** Address ******
Id: 4
First Line: Line 41
Second Line: Line 42
City: null
Zip Code: 22331
Person Id: 1
***** Address ******

Person
**** Person **** Id: 2
First name: Steve
Last name: Jobs
**** Person **** 

Address
***** Address ******
Id: 5
First Line: Line 111
Second Line: Line 112
City: null
Zip Code: 12345
Person Id: 2
***** Address ******

Person
**** Person **** Id: 2
First name: Steve
Last name: Jobs
**** Person **** 

Address
***** Address ******
Id: 6
First Line: Line 221
Second Line: Line 222
City: null
Zip Code: 54321
Person Id: 2
***** Address ******

Person
**** Person **** Id: 2
First name: Steve
Last name: Jobs
**** Person **** 

Address
***** Address ******
Id: 7
First Line: Line 331
Second Line: Line 332
City: null
Zip Code: 11221
Person Id: 2
***** Address ******

Person
**** Person **** Id: 2
First name: Steve
Last name: Jobs
**** Person **** 

Address
***** Address ******
Id: 8
First Line: Line 441
Second Line: Line 442
City: null
Zip Code: 22331
Person Id: 2
***** Address ******

Person
**** Person **** Id: 3
First name: Clark
Last name: Jacob
**** Person **** 

Address
***** Address ******
Id: 9
First Line: Line 111
Second Line: Line 112
City: null
Zip Code: 12345
Person Id: 3
***** Address ******

Person
**** Person **** Id: 3
First name: Clark
Last name: Jacob
**** Person **** 

Address
***** Address ******
Id: 10
First Line: Line 221
Second Line: Line 222
City: null
Zip Code: 54321
Person Id: 3
***** Address ******

All the data is retrieved in a single SQL. The generated query is an outer join between the PERSON and ADDRESS tables. This is efficient except for the fact that the Person object is repeated for the number of addresses. Alternatively change the Fetch annotation on the getAddresses method to the following:

	@OneToMany(mappedBy="person", cascade=CascadeType.ALL)
	@Column(name="id")
	@Fetch(FetchMode.JOIN)
	//@Fetch(FetchMode.SUBSELECT)
	//@BatchSize(size=2)
	public List<Address> getAddresses() {
		return addresses;
	}

Run the DataSelectFetch class. Here’s the ouput:

Retrieving Data
Hibernate: select person0_.ID as ID0_, person0_.FIRST_NAME as FIRST2_0_, person0_.LAST_NAME as LAST3_0_ from SYSTEM.PERSON person0_
Hibernate: select addresses0_.PERSON_ID as PERSON4_0_1_, addresses0_.id as id1_, addresses0_.id as id1_0_, 
addresses0_.CITY as CITY1_0_, addresses0_.FIRST_LINE as FIRST3_1_0_, addresses0_.PERSON_ID as PERSON4_1_0_, addresses0_.SECOND_LINE as SECOND5_1_0_, addresses0_.ZIP_CODE as ZIP6_1_0_ from SYSTEM.ADDRESS addresses0_ where addresses0_.PERSON_ID=?
Hibernate: select addresses0_.PERSON_ID as PERSON4_0_1_, addresses0_.id as id1_, addresses0_.id as id1_0_, addresses0_.CITY as CITY1_0_, addresses0_.FIRST_LINE as FIRST3_1_0_, addresses0_.PERSON_ID as PERSON4_1_0_, addresses0_.SECOND_LINE as SECOND5_1_0_, addresses0_.ZIP_CODE as ZIP6_1_0_ from SYSTEM.ADDRESS addresses0_ where addresses0_.PERSON_ID=?
Hibernate: select addresses0_.PERSON_ID as PERSON4_0_1_, addresses0_.id as id1_, addresses0_.id as id1_0_, addresses0_.CITY as CITY1_0_, addresses0_.FIRST_LINE as FIRST3_1_0_, addresses0_.PERSON_ID as PERSON4_1_0_, addresses0_.SECOND_LINE as SECOND5_1_0_, addresses0_.ZIP_CODE as ZIP6_1_0_ from SYSTEM.ADDRESS addresses0_ where addresses0_.PERSON_ID=?
Data retrieved: 3
**** Person **** Id: 1
First name: Bill
Last name: Banks
**** Person **** 

Address retrieval initiated.
Address retrieval complete.
#### individual address: 1
***** Address ******
Id: 1
First Line: Line 11
Second Line: Line 12
City: null
Zip Code: 12345
Person Id: 1
***** Address ******

#### Address complete
#### individual address: 2
***** Address ******
Id: 2
First Line: Line 21
Second Line: Line 22
City: null
Zip Code: 54321
Person Id: 1
***** Address ******

#### Address complete
#### individual address: 3
***** Address ******
Id: 3
First Line: Line 31
Second Line: Line 32
City: null
Zip Code: 11221
Person Id: 1
***** Address ******

#### Address complete
#### individual address: 4
***** Address ******
Id: 4
First Line: Line 41
Second Line: Line 42
City: null
Zip Code: 22331
Person Id: 1
***** Address ******

#### Address complete
**** Person **** Id: 2
First name: Steve
Last name: Jobs
**** Person **** 

Address retrieval initiated.
Address retrieval complete.
#### individual address: 1
***** Address ******
Id: 5
First Line: Line 111
Second Line: Line 112
City: null
Zip Code: 12345
Person Id: 2
***** Address ******

#### Address complete
#### individual address: 2
***** Address ******
Id: 6
First Line: Line 221
Second Line: Line 222
City: null
Zip Code: 54321
Person Id: 2
***** Address ******

#### Address complete
#### individual address: 3
***** Address ******
Id: 7
First Line: Line 331
Second Line: Line 332
City: null
Zip Code: 11221
Person Id: 2
***** Address ******

#### Address complete
#### individual address: 4
***** Address ******
Id: 8
First Line: Line 441
Second Line: Line 442
City: null
Zip Code: 22331
Person Id: 2
***** Address ******

#### Address complete
**** Person **** Id: 3
First name: Clark
Last name: Jacob
**** Person **** 

Address retrieval initiated.
Address retrieval complete.
#### individual address: 1
***** Address ******
Id: 9
First Line: Line 111
Second Line: Line 112
City: null
Zip Code: 12345
Person Id: 3
***** Address ******

#### Address complete
#### individual address: 2
***** Address ******
Id: 10
First Line: Line 221
Second Line: Line 222
City: null
Zip Code: 54321
Person Id: 3
***** Address ******

#### Address complete

Four SQLs are fired. First to retrieve all Persons and the next three for retrieving associated addresses for that person. This seems similar to the SELECT fetch strategy except that fact that all database retrieval take place upfront in JOIN fetch unlike in SELECT where it happens on a need basis. This can become an important performance consideration.

Update 18th Nov 2011: This does not really look like a join query. I changed the querying class to the following class:

package com.tutorial.hibernate.fetch;

import java.util.List;

import org.hibernate.Session;
import org.hibernate.SessionFactory;

public class DataFetchJoin {

	public static void main(String[] args) {
		SessionFactory fact = HibernateUtil.getFactory();
		Session session = fact.openSession();
		
		Person p = (Person)session.get(Person.class, 1);
		
		System.out.println("Retrieving Data");
		System.out.println(p);
		System.out.println("Address retrieval initiated.");
		List<Address> addresses = p.getAddresses();
		System.out.println("Address retrieval complete.");
		int i=1;
		for (Address address : addresses) {
			System.out.println("#### individual address: " + i);
			System.out.println(address);
			System.out.println("#### Address complete");
			i++;
		}
	}
}

On running the test class, the console output is as follows:

Hibernate: select person0_.ID as ID0_1_, person0_.FIRST_NAME as FIRST2_0_1_, person0_.LAST_NAME as LAST3_0_1_, addresses1_.PERSON_ID as PERSON4_0_3_, addresses1_.id as id3_, addresses1_.id as id1_0_, addresses1_.CITY as CITY1_0_, addresses1_.FIRST_LINE as FIRST3_1_0_, addresses1_.PERSON_ID as PERSON4_1_0_, addresses1_.SECOND_LINE as SECOND5_1_0_, addresses1_.ZIP_CODE as ZIP6_1_0_ from SYSTEM.PERSON person0_ left outer join SYSTEM.ADDRESS addresses1_ on person0_.ID=addresses1_.PERSON_ID where person0_.ID=?
Retrieving Data
**** Person **** Id: 1
First name: Bill
Last name: Banks
**** Person **** 

Address retrieval initiated.
Address retrieval complete.
#### individual address: 1
***** Address ******
Id: 1
First Line: Line 11
Second Line: Line 12
City: null
Zip Code: 12345
Person Id: 1
***** Address ******

#### Address complete
#### individual address: 2
***** Address ******
Id: 2
First Line: Line 21
Second Line: Line 22
City: null
Zip Code: 54321
Person Id: 1
***** Address ******

#### Address complete
#### individual address: 3
***** Address ******
Id: 3
First Line: Line 31
Second Line: Line 32
City: null
Zip Code: 11221
Person Id: 1
***** Address ******

#### Address complete
#### individual address: 4
***** Address ******
Id: 4
First Line: Line 41
Second Line: Line 42
City: null
Zip Code: 22331
Person Id: 1
***** Address ******

#### Address complete

This is more on expected lines for JOIN mode. The difference was that here I retrieved one Person only vis-a-vis the earlier queries retrieved N persons. Hibernate querying is complex and too flexible for my comfort.
End Update:18th Nov 2011

Fetch Strategy : SUBSELECT

Let’s move on to the next fetch strategy SUBSELECT. Change the fetch mode in getAddresses annotation to the following:

	@OneToMany(mappedBy="person", cascade=CascadeType.ALL)
	@Column(name="id")
	@Fetch(FetchMode.SUBSELECT)
	//@BatchSize(size=2)
	public List<Address> getAddresses() {
		return addresses;
	}

Run the DataSelectFetch class. The output is as follows:

Retrieving Data
Hibernate: select person0_.ID as ID0_, person0_.FIRST_NAME as FIRST2_0_, person0_.LAST_NAME as LAST3_0_ from SYSTEM.PERSON person0_
Data retrieved: 3
**** Person **** Id: 1
First name: Bill
Last name: Banks
**** Person **** 

Address retrieval initiated.
Address retrieval complete.
Hibernate: select addresses0_.PERSON_ID as PERSON4_0_1_, addresses0_.id as id1_, addresses0_.id as id1_0_, addresses0_.CITY as CITY1_0_, addresses0_.FIRST_LINE as FIRST3_1_0_, addresses0_.PERSON_ID as PERSON4_1_0_, addresses0_.SECOND_LINE as SECOND5_1_0_, addresses0_.ZIP_CODE as ZIP6_1_0_ from SYSTEM.ADDRESS addresses0_ where addresses0_.PERSON_ID in (select person0_.ID from SYSTEM.PERSON person0_)
#### individual address: 1
***** Address ******
Id: 1
First Line: Line 11
Second Line: Line 12
City: null
Zip Code: 12345
Person Id: 1
***** Address ******

#### Address complete
#### individual address: 2
***** Address ******
Id: 2
First Line: Line 21
Second Line: Line 22
City: null
Zip Code: 54321
Person Id: 1
***** Address ******

#### Address complete
#### individual address: 3
***** Address ******
Id: 3
First Line: Line 31
Second Line: Line 32
City: null
Zip Code: 11221
Person Id: 1
***** Address ******

#### Address complete
#### individual address: 4
***** Address ******
Id: 4
First Line: Line 41
Second Line: Line 42
City: null
Zip Code: 22331
Person Id: 1
***** Address ******

#### Address complete
**** Person **** Id: 2
First name: Steve
Last name: Jobs
**** Person **** 

Address retrieval initiated.
Address retrieval complete.
#### individual address: 1
***** Address ******
Id: 5
First Line: Line 111
Second Line: Line 112
City: null
Zip Code: 12345
Person Id: 2
***** Address ******

#### Address complete
#### individual address: 2
***** Address ******
Id: 6
First Line: Line 221
Second Line: Line 222
City: null
Zip Code: 54321
Person Id: 2
***** Address ******

#### Address complete
#### individual address: 3
***** Address ******
Id: 7
First Line: Line 331
Second Line: Line 332
City: null
Zip Code: 11221
Person Id: 2
***** Address ******

#### Address complete
#### individual address: 4
***** Address ******
Id: 8
First Line: Line 441
Second Line: Line 442
City: null
Zip Code: 22331
Person Id: 2
***** Address ******

#### Address complete
**** Person **** Id: 3
First name: Clark
Last name: Jacob
**** Person **** 

Address retrieval initiated.
Address retrieval complete.
#### individual address: 1
***** Address ******
Id: 9
First Line: Line 111
Second Line: Line 112
City: null
Zip Code: 12345
Person Id: 3
***** Address ******

#### Address complete
#### individual address: 2
***** Address ******
Id: 10
First Line: Line 221
Second Line: Line 222
City: null
Zip Code: 54321
Person Id: 3
***** Address ******

#### Address complete

Two SQLs are fired. One to retrieve all Persons and the second uses a SUBSELECT query in the WHERE clause to retrieve all addresses that has matching person ids.

Let’s change line number 15 in DataSelectFetch from

		Query q = session.createQuery(" FROM Person p ");

		Query q = session.createQuery(" FROM Person p WHERE p.id = ? OR p.id = ?");
		q.setInteger(0, 1);
		q.setInteger(1, 2);

The two database queries are changed to the following:

Hibernate: select person0_.ID as ID0_, person0_.FIRST_NAME as FIRST2_0_, person0_.LAST_NAME as LAST3_0_ from SYSTEM.PERSON person0_ where person0_.ID=? or person0_.ID=?
Hibernate: select addresses0_.PERSON_ID as PERSON4_0_1_, addresses0_.id as id1_, addresses0_.id as id1_0_, addresses0_.CITY as CITY1_0_, addresses0_.FIRST_LINE as FIRST3_1_0_, addresses0_.PERSON_ID as PERSON4_1_0_, addresses0_.SECOND_LINE as SECOND5_1_0_, addresses0_.ZIP_CODE as ZIP6_1_0_ from SYSTEM.ADDRESS addresses0_ where addresses0_.PERSON_ID in (select person0_.ID from SYSTEM.PERSON person0_ where person0_.ID=? or person0_.ID=?)

Fetch Strategy : BATCH

Now let’s look at the last fetch strategy i.e. batch.

Change the getAddresses annotation to the following:

	@OneToMany(mappedBy="person", cascade=CascadeType.ALL)
	@Column(name="id")
	@BatchSize(size=2)
	public List<Address> getAddresses() {
		return addresses;
	}

Run the DataSelectFetch class. This will be the older version of the class without the changes as suggested for Subselect option. The console output is:

Retrieving Data
Hibernate: select person0_.ID as ID0_, person0_.FIRST_NAME as FIRST2_0_, person0_.LAST_NAME as LAST3_0_ from SYSTEM.PERSON person0_
Data retrieved: 3
**** Person **** Id: 1
First name: Bill
Last name: Banks
**** Person **** 

Address retrieval initiated.
Address retrieval complete.
Hibernate: select addresses0_.PERSON_ID as PERSON4_0_1_, addresses0_.id as id1_, addresses0_.id as id1_0_, addresses0_.CITY as CITY1_0_, addresses0_.FIRST_LINE as FIRST3_1_0_, addresses0_.PERSON_ID as PERSON4_1_0_, addresses0_.SECOND_LINE as SECOND5_1_0_, addresses0_.ZIP_CODE as ZIP6_1_0_ from SYSTEM.ADDRESS addresses0_ where addresses0_.PERSON_ID in (?, ?)
#### individual address: 1
***** Address ******
Id: 1
First Line: Line 11
Second Line: Line 12
City: null
Zip Code: 12345
Person Id: 1
***** Address ******

#### Address complete
#### individual address: 2
***** Address ******
Id: 2
First Line: Line 21
Second Line: Line 22
City: null
Zip Code: 54321
Person Id: 1
***** Address ******

#### Address complete
#### individual address: 3
***** Address ******
Id: 3
First Line: Line 31
Second Line: Line 32
City: null
Zip Code: 11221
Person Id: 1
***** Address ******

#### Address complete
#### individual address: 4
***** Address ******
Id: 4
First Line: Line 41
Second Line: Line 42
City: null
Zip Code: 22331
Person Id: 1
***** Address ******

#### Address complete
**** Person **** Id: 2
First name: Steve
Last name: Jobs
**** Person **** 

Address retrieval initiated.
Address retrieval complete.
Hibernate: select addresses0_.PERSON_ID as PERSON4_0_1_, addresses0_.id as id1_, addresses0_.id as id1_0_, addresses0_.CITY as CITY1_0_, addresses0_.FIRST_LINE as FIRST3_1_0_, addresses0_.PERSON_ID as PERSON4_1_0_, addresses0_.SECOND_LINE as SECOND5_1_0_, addresses0_.ZIP_CODE as ZIP6_1_0_ from SYSTEM.ADDRESS addresses0_ where addresses0_.PERSON_ID=?
#### individual address: 1
***** Address ******
Id: 5
First Line: Line 111
Second Line: Line 112
City: null
Zip Code: 12345
Person Id: 2
***** Address ******

#### Address complete
#### individual address: 2
***** Address ******
Id: 6
First Line: Line 221
Second Line: Line 222
City: null
Zip Code: 54321
Person Id: 2
***** Address ******

#### Address complete
#### individual address: 3
***** Address ******
Id: 7
First Line: Line 331
Second Line: Line 332
City: null
Zip Code: 11221
Person Id: 2
***** Address ******

#### Address complete
#### individual address: 4
***** Address ******
Id: 8
First Line: Line 441
Second Line: Line 442
City: null
Zip Code: 22331
Person Id: 2
***** Address ******

#### Address complete
**** Person **** Id: 3
First name: Clark
Last name: Jacob
**** Person **** 

Address retrieval initiated.
Address retrieval complete.
#### individual address: 1
***** Address ******
Id: 9
First Line: Line 111
Second Line: Line 112
City: null
Zip Code: 12345
Person Id: 3
***** Address ******

#### Address complete
#### individual address: 2
***** Address ******
Id: 10
First Line: Line 221
Second Line: Line 222
City: null
Zip Code: 54321
Person Id: 3
***** Address ******

#### Address complete

The batch size maps to the number of persons whose addresses are retrieved. In the present case the first batch is triggered for Person with id 1 and 3, the second batch is for Person with id is 2. I am not sure why hibernate deviates from the order in which the ids are retrieved. Need to figure that out.

To sum up we have four different methods/strategies hibernate provides to retrieve data. It is upto the developer to judiciously choose one of the four strategies which ensures optimum application and database performance.

That’s all at the moment.

Let’s start with creating a class which spawns a thread. Java provides two approaches for creating threads, one create a Thread sub class or implement Runnable interface. Subclassing Thread is a bad idea because it constraints the developer from developing a domain specific inheritance hierarchy. The class can only extend Thread. Instead implementing Runnable interface is a more suitable option. So let’s create a new class Activity class which implements Runnable interface. Refer the code below for the class source.

package com.concurrency;

public class Activity implements Runnable {

	@Override
	public void run() {
		System.out.println("Running concurrent activity!");
	}

}

To spawn a Activity thread, we create an Thread instance with the Activity instance as the constructor argument. Look at the source code of ThreadSpawner class.

package com.concurrency.test;

import com.concurrency.Activity;

public class ThreadSpawner {

	public static void main(String[] args) {
		Thread t = new Thread(new Activity());
		t.start();
	}

}

This is the pre Java 5 days way of creating a java thread. In post Java 5 days, Java has introduced new classes. One of the concurrency classes added in Java 5 is the Executors class. This class provided a number of utility methods. One of the method is defaultThreadFactory which creates a ThreadFactory class instance which can be used spawn new threads. An alternative approach to creating a new thread is explained in ThreadFactoryTest class. Here’s the class source code:

package com.concurrency.tf.test;

import java.util.concurrent.Executors;
import java.util.concurrent.ThreadFactory;

import com.concurrency.Activity;

public class ThreadFactoryTest {

	public static void main(String[] args) {
		ThreadFactory tf = Executors.defaultThreadFactory();
		Thread t = tf.newThread(new Activity());
		t.start();		
	}

}

Using Executors’s defaultThreadFactory, a ThreadFactory instance is created. To the ThreadFactory instance’s newThread method a Runnable instance whose thread needs to be spawned is passed. I have used the same Activity class to help understand the similarities and differences in the two approaches: the pre Java 5 and post Java 5 approach.So now the most important question is what’s the benefit of using Executors and ThreadFactory classes? I was able to figure out that using the Java 5 concurrency framework provides the newly created thread with an automatically assigned thread group name, thread pool name and thread name. Beyond that I am not sure if there are any additional benefits the Executors framework provides.

Parallel computing or parallelization is an important programming paradigm which speeds up a sequentially executing program. Java does not allow developers to spawn new processes; it allows spawning of threads. Breaking a task into sub activities which can be ran in parallel helps reduce the overall task processing time. However one needs to keep in mind that such an approach if uncontrolled can lead to spawning of large number of threads. Threads in large quantities can put a strain on JVM resources (CPU, memory). Therefore it is necessary to put in place a method to limit the number of threads to a threshold, the Executors framework provides such a mechanism.

The Executors framework allows the creation of thread pool.Executors supports creation of a cachable, fixed and scheduled thread pool. Let’s try and understand each thread pool type with an example. To begin with let’s create a Runnable implementation which can be reused for all the pools. The class we create is PoolRunnable and below is its source code.

package com.concurrency.pool;

import java.text.SimpleDateFormat;

import com.concurrency.utils.ConcurrencyUtils;

public class PoolRunnable implements Runnable {

	private int delayTime = 0;
	
	public PoolRunnable(int delayTime) {
		this.delayTime = delayTime;
	}
	
	public PoolRunnable() {
		
	}
	
	@Override
	public void run() {
		Thread curThread = Thread.currentThread();
		SimpleDateFormat df = new SimpleDateFormat("yyyy-MM-dd 'at' HH:mm:ss");
		System.out.println(df.format(new java.util.Date()) + " Starting thread " + curThread.getName());
		try {
			Thread.sleep(delayTime * 1000);
		} catch (InterruptedException e) {
			e.printStackTrace();
		}
		System.out.println("@@@@@@@@@@@@@@@@@");
		System.out.println(this.toString());
		System.out.println(df.format(new java.util.Date()) + " Ending thread " + curThread.getName());
		System.out.println("#################");
	}

	@Override
	public String toString() {
		return ConcurrencyUtils.getThreadInfo();
	}
		
}

The goal of the PoolRunnable class is to spawn a thread which is to replicate a typical application behavior by sleeping for a user defined time duration. The end user configures the PoolRunnable sleep duration by passing the interval as a constructor argument. PoolRunnable also utilizes a utility class ConcurrencyUtils for its toString implementation. Here’s the source code.

package com.concurrency.utils;

import java.text.SimpleDateFormat;

public class ConcurrencyUtils {
	
	public static String getThreadInfo() {
		StringBuilder sb = new StringBuilder();
		Thread curThread = Thread.currentThread();
		sb.append("Thread Id: ");
		sb.append(curThread.getId());
		sb.append("\n");
		sb.append("Name: ");
		sb.append(curThread.getName());
		sb.append("\n");
		sb.append("Group: ");
		sb.append(curThread.getThreadGroup().getName());
		sb.append("\n");
		return sb.toString();
	}

	public static String getShortThreadInfo() {
		StringBuilder sb = new StringBuilder();
		Thread curThread = Thread.currentThread();
		sb.append("Thread Id: ");
		sb.append(curThread.getId());
		sb.append(", ");
		sb.append("Name: ");
		sb.append(curThread.getName());
		sb.append(", ");
		sb.append("Group: ");
		sb.append(curThread.getThreadGroup().getName());
		sb.append("\n");
		return sb.toString();
	}

	public static String retrieveCurrentDate(){
		SimpleDateFormat df = new SimpleDateFormat("yyyy-MM-dd 'at' HH:mm:ss");
		return df.format(new java.util.Date());
	}
		
}

To understand the cached thread pool functioning consider the following CachedPoolTest implementation:

package com.concurrency.pool.ctp.test;

import java.util.concurrent.ExecutorService;
import java.util.concurrent.Executors;
import java.util.concurrent.ThreadFactory;
import java.util.concurrent.ThreadPoolExecutor;

import com.concurrency.pool.PoolRunnable;

public class CachedPoolTest {

	public static void main(String[] args) {
		ExecutorService svc = Executors.newCachedThreadPool();
			
		Runnable r1 = new PoolRunnable();
		svc.execute(r1);
		
		try {
			Thread.sleep(1000);
		} catch (InterruptedException e) {
			e.printStackTrace();
		}
		
		Runnable r2 = new PoolRunnable(1);
		svc.execute(r2);

		try {
			Thread.sleep(1200);
		} catch (InterruptedException e) {
			e.printStackTrace();
		}

		Runnable r3 = new PoolRunnable(2);
		svc.execute(r3);

		try {
			Thread.sleep(2100);
		} catch (InterruptedException e) {
			e.printStackTrace();
		}
		
		svc.shutdown();
	}

}

The line 13 creates a ExecutorService which retains a handle to the cached thread pool. By default, a pool having minimum size zero and max size equivalent of maximum integer value is created.An unused thread is retained in the cached pool for a duration of 60 seconds; beyond which the thread is removed from the pool.

The test class CachedPoolTest executes three Runnable instances of PoolRunnable class each provided a sleep duration of 0, 1 and 2 seconds respectively. The instances are individually submitted to execute method of the ExecutorService. For proper testing it is essential that the first thread is allowed to complete before triggering the subsequent thread. This is achieved by introducing a delay(1 sec, 1.2 sec, 2.1 sec) between each execute method invocation. Here’s the test class run output:

2011-05-13 at 14:52:15 Starting thread pool-1-thread-1
@@@@@@@@@@@@@@@@@
Thread Id: 8
Name: pool-1-thread-1
Group: main

2011-05-13 at 14:52:15 Ending thread pool-1-thread-1
#################
2011-05-13 at 14:52:16 Starting thread pool-1-thread-1
@@@@@@@@@@@@@@@@@
Thread Id: 8
Name: pool-1-thread-1
Group: main

2011-05-13 at 14:52:17 Ending thread pool-1-thread-1
#################
2011-05-13 at 14:52:17 Starting thread pool-1-thread-1
@@@@@@@@@@@@@@@@@
Thread Id: 8
Name: pool-1-thread-1
Group: main

2011-05-13 at 14:52:19 Ending thread pool-1-thread-1
#################

I have used concurrency utils to print thread id, name and pool information. From the output it is clear that all reuse the same thread. One more thing to note is the line 42. Invocation of shutdown method on ExecutorService is important else the Java process will not terminate.

I have enhanced to add a fourth Runnable instance which will be executed after 61 seconds. This is to verify if a new thread is created after the expiration of the cache thread retention duration. The test class run output proves me correct. Below is the enhanced class and its output.

package com.concurrency.pool.ctp.test;

import java.util.concurrent.ExecutorService;
import java.util.concurrent.Executors;
import java.util.concurrent.ThreadFactory;
import java.util.concurrent.ThreadPoolExecutor;

import com.concurrency.pool.PoolRunnable;

public class CachedPoolTest {

	public static void main(String[] args) {
		ExecutorService svc = Executors.newCachedThreadPool();
			
		Runnable r1 = new PoolRunnable();
		svc.execute(r1);
		
		try {
			Thread.sleep(1000);
		} catch (InterruptedException e) {
			e.printStackTrace();
		}
		
		Runnable r2 = new PoolRunnable(1);
		svc.execute(r2);

		try {
			Thread.sleep(1200);
		} catch (InterruptedException e) {
			e.printStackTrace();
		}

		Runnable r3 = new PoolRunnable(2);
		svc.execute(r3);

		try {
			Thread.sleep(2100);
		} catch (InterruptedException e) {
			e.printStackTrace();
		}
		
		try {
			Thread.sleep(61000);
		} catch (InterruptedException e) {
			e.printStackTrace();
		}

		Runnable r4 = new PoolRunnable();
		svc.execute(r4);

		
		svc.shutdown();
	}

}

2011-05-13 at 15:00:22 Starting thread pool-1-thread-1
@@@@@@@@@@@@@@@@@
Thread Id: 8
Name: pool-1-thread-1
Group: main

2011-05-13 at 15:00:22 Ending thread pool-1-thread-1
#################
2011-05-13 at 15:00:23 Starting thread pool-1-thread-1
@@@@@@@@@@@@@@@@@
Thread Id: 8
Name: pool-1-thread-1
Group: main

2011-05-13 at 15:00:24 Ending thread pool-1-thread-1
#################
2011-05-13 at 15:00:24 Starting thread pool-1-thread-1
@@@@@@@@@@@@@@@@@
Thread Id: 8
Name: pool-1-thread-1
Group: main

2011-05-13 at 15:00:26 Ending thread pool-1-thread-1
#################
2011-05-13 at 15:01:27 Starting thread pool-1-thread-2
@@@@@@@@@@@@@@@@@
Thread Id: 9
Name: pool-1-thread-2
Group: main

2011-05-13 at 15:01:27 Ending thread pool-1-thread-2
#################

So we have looked at cached thread pool. Now let’s focus on the other types. First let’s look at the fixed thread pool. I have created the FixedThreadPoolTest class for explaining fixed thread pool. Refer the source code below:

package com.concurrency.pool.fp;

import java.util.concurrent.ExecutorService;
import java.util.concurrent.Executors;

import com.concurrency.pool.PoolRunnable;

public class FixedThreadPoolTest {

	public static void main(String[] args) {
		ExecutorService svc = Executors.newFixedThreadPool(2);
		
		Runnable r1 = new PoolRunnable(2);
		svc.execute(r1);
				
		Runnable r2 = new PoolRunnable(3);
		svc.execute(r2);

		Runnable r3 = new PoolRunnable(3);
		svc.execute(r3);
		
		svc.shutdown();
		
	}
}

The line 11 in the test class creates a fixed thread pool containing 2 threads. I then execute three threads at nearly the same time with individual thread sleep durations 2 seconds, 3 seconds and 3 seconds respectively. the output observed is as below.

2011-05-13 at 15:14:26 Starting thread pool-1-thread-1
2011-05-13 at 15:14:26 Starting thread pool-1-thread-2
@@@@@@@@@@@@@@@@@
Thread Id: 8
Name: pool-1-thread-1
Group: main

2011-05-13 at 15:14:28 Ending thread pool-1-thread-1
#################
2011-05-13 at 15:14:28 Starting thread pool-1-thread-1
@@@@@@@@@@@@@@@@@
Thread Id: 9
Name: pool-1-thread-2
Group: main

2011-05-13 at 15:14:29 Ending thread pool-1-thread-2
#################
@@@@@@@@@@@@@@@@@
Thread Id: 8
Name: pool-1-thread-1
Group: main

2011-05-13 at 15:14:31 Ending thread pool-1-thread-1
#################

The test class run output shows that two threads are started simultaneously, one thread completes its run after 2 seconds. On termination of this thread, the third thread is spawned which terminates after 3 seconds. The test clearly shows that the 2 thread upper limit defined during the thread pool creation is honored and any new thread requests beyond the threshold limit are queued until existing pool thread(s) become available.

Sometimes during programming we have a requirement of triggering a specific functionality or a set of
functionalities after a designated period of time. The Executors framework provides a facility to create scheduled thread pool. Refer the source code of the test class ScheduleConcurrencyTest

package com.concurrency.schedule.test;

import java.text.SimpleDateFormat;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.Executors;
import java.util.concurrent.ScheduledExecutorService;
import java.util.concurrent.ScheduledFuture;
import java.util.concurrent.TimeUnit;

import com.concurrency.Calculator;
import com.concurrency.pool.PoolRunnable;

public class ScheduleConcurrencyTest {

	public static void main(String[] args) {
		SimpleDateFormat df = new SimpleDateFormat("yyyy-MM-dd 'at' HH:mm:ss");
		ScheduledExecutorService svc = Executors.newScheduledThreadPool(2);
		System.out.println(df.format(new java.util.Date()) + " Time Runnable");
		svc.schedule(new PoolRunnable(), 2, TimeUnit.SECONDS);
		System.out.println(df.format(new java.util.Date()) + " Time Callable");
		ScheduledFuture<Integer> sf = svc.schedule(new Calculator(1, 3, 
			Calculator.OPERATION_ADD), 5, TimeUnit.SECONDS);
		try {
			System.out.println("Waiting for value.");
			Integer val = sf.get();
			System.out.println(df.format(new java.util.Date()) + " Time Callable Retrieve");
			System.out.println("Computed Value: " + val);
		} catch (InterruptedException e) {
			e.printStackTrace();
		} catch (ExecutionException e) {
			e.printStackTrace();
		}
		
		svc.shutdown();
		
	}
}

Refer line 17 of ScheduleConcurrencyTest. Here we create a scheduled thread pool and get a handle to the underlying pool via the ScheduledExecutorService interface. Next look at line 19. Here we schedule a PoolRunnable instance to be run after a delay of 2 seconds. Runnable implementation basically constitutes functionality which needs to be executed in parallel with the invoking application. Some times we expect the thread to do some processing and return some value. Java 5 has introduced the Callable construct. This allows threads to return values to the invoking application.

The ScheduledExecutorService allows execution of Callable interface after a defined time interval. I create a
calculator implementation of Callable interface. The Calculator is expected to add two integer values and respond back with the sum value. The source code of Calculator class handling Callable idiosyncrasies is shown below:

package com.concurrency;

import java.util.concurrent.Callable;

public class Calculator implements Callable<Integer> {
	
	public static final int OPERATION_ADD = 1;
	
	private int param1 = 0;
	private int param2 = 0;
	private int operation = 0;
	
	public Calculator(int param1, int param2, int operation) {
		this.param1 = param1;
		this.param2 = param2;
		this.operation = operation;
	}

	public int getParam1() {
		return param1;
	}

	public void setParam1(int param1) {
		this.param1 = param1;
	}

	public int getParam2() {
		return param2;
	}

	public void setParam2(int param2) {
		this.param2 = param2;
	}

	public int getOperation() {
		return operation;
	}

	public void setOperation(int operation) {
		this.operation = operation;
	}
	
	@Override
	public Integer call() throws Exception {
		int retValue = 0;
		switch (this.operation) {
		case 1:
			retValue = this.param1 + this.param2;
			break;
		// Additional cases can be similarly added for 
		//other mathematical operations
			
		default:
			retValue = 0;
			break;
		}
		return Integer.valueOf(retValue) ;
	}
}

Refer line 21 in the ScheduleConcurrencyTest. Here we schedule Calculator for execution after passage of 5 seconds. In line 25 we get the return value from the Calculator which can be used for further processing. The test run output is shown below.

2011-05-13 at 16:48:17 Time Runnable
2011-05-13 at 16:48:17 Time Callable
Waiting for value.
2011-05-13 at 16:48:19 Starting thread pool-1-thread-1
@@@@@@@@@@@@@@@@@
Thread Id: 8
Name: pool-1-thread-1
Group: main

2011-05-13 at 16:48:19 Ending thread pool-1-thread-1
#################
2011-05-13 at 16:48:22 Time Callable Retrieve
Computed Value: 4

Clearly line 4 and 12 of the output show that PoolRunnable instance is invoked after a delay of 2 seconds, and Calculator is invoked after completion of 5 seconds. The schedule example used above is a case where the schedule task/job is to processed on a one time basis only. However in real life scenarios, we might need the ability to trigger a task at regular intervals in time or after a fixed period after the completion of the specific task. The Executors framework provides two methods namely scheduleAtFixedRate and scheduleWithFixedDelay to implement the same.

Let’s take the first example of scheduleAtFixedRate. Refer the test class ScheduleIntervalTest’s source code:

package com.concurrency.schedule.test;

import java.util.concurrent.Executors;
import java.util.concurrent.ScheduledExecutorService;
import java.util.concurrent.TimeUnit;

import com.concurrency.ScheduleJob;

public class ScheduleIntervalTest {

	public static void main(String[] args) {
		ScheduledExecutorService svc = Executors.newScheduledThreadPool(2);
		svc.scheduleAtFixedRate(new ScheduleJob(), 2, 2, TimeUnit.SECONDS);

	}
}

To understand the functionality better, I have created a new Runnable implementation ScheduleJob, here’s
ScheduleJob’s source code:

package com.concurrency;

import java.text.SimpleDateFormat;

public class ScheduleJob implements Runnable {
	
	private static int counter = 0;
	
	public ScheduleJob() {
		
	}

	@Override
	public void run() {
		try {
			if (counter == 5) {
				System.out.println("Exception is thrown!");
				throw new RuntimeException("Job cannot be processed.");
			}
			SimpleDateFormat df = new SimpleDateFormat("yyyy-MM-dd 'at' HH:mm:ss");
			System.out.println(df.format(new java.util.Date()) + " job ran.");
			counter++;
		} catch(Throwable t) {
			t.printStackTrace();
			counter = 0;
		}
	}
}

The ScheduleJob has been programmed to throw a RuntimeException on its sixth run. The idea is to determine if the schedule job is affected by the exception or not. Here’s the test output run:

2011-05-13 at 17:13:05 job ran.
2011-05-13 at 17:13:07 job ran.
2011-05-13 at 17:13:09 job ran.
2011-05-13 at 17:13:11 job ran.
2011-05-13 at 17:13:13 job ran.
Exception is thrown!
java.lang.RuntimeException: Job cannot be processed.
	at com.concurrency.ScheduleJob.run(ScheduleJob.java:18)
	at java.util.concurrent.Executors$RunnableAdapter.call(Unknown Source)
	at java.util.concurrent.FutureTask$Sync.innerRunAndReset(Unknown Source)
	at java.util.concurrent.FutureTask.runAndReset(Unknown Source)
	at java.util.concurrent.ScheduledThreadPoolExecutor$ScheduledFutureTask.access$101(Unknown Source)
	at java.util.concurrent.ScheduledThreadPoolExecutor$ScheduledFutureTask.runPeriodic(Unknown Source)
	at java.util.concurrent.ScheduledThreadPoolExecutor$ScheduledFutureTask.run(Unknown Source)
	at java.util.concurrent.ThreadPoolExecutor$Worker.runTask(Unknown Source)
	at java.util.concurrent.ThreadPoolExecutor$Worker.run(Unknown Source)
	at java.lang.Thread.run(Unknown Source)
2011-05-13 at 17:13:17 job ran.
2011-05-13 at 17:13:19 job ran.
:
:
:

The job continues running every 2nd second as defined during the scheduleAtFixedRate method invocation.
Now moving on to the scheduleWithFixedDelay method. For understanding this, I am creating a new Runnable
implementation ScheduleDelayJob. During the thread run, the thread sleeps for a duration which is incremented by one for each subsequent invocation.

package com.concurrency;

import java.text.SimpleDateFormat;

public class ScheduleDelayJob implements Runnable {

	private static int counter = 1;
	
	@Override
	public void run() {
		SimpleDateFormat df = new SimpleDateFormat("yyyy-MM-dd 'at' HH:mm:ss");
		System.out.println(df.format(new java.util.Date()) + " Starting run.");
		
		try {
			Thread.sleep(counter * 1000);
			counter++;
		} catch (InterruptedException e) {
			e.printStackTrace();
		}
		System.out.println(df.format(new java.util.Date()) + " Ending run.");
	}
}

Refer the ScheduleDelayTest test class:

package com.concurrency.schedule.test;

import java.util.concurrent.Executors;
import java.util.concurrent.ScheduledExecutorService;
import java.util.concurrent.TimeUnit;

import com.concurrency.ScheduleDelayJob;

public class ScheduleDelayTest {

	public static void main(String[] args) {
		ScheduledExecutorService svc = Executors.newScheduledThreadPool(2);
		svc.scheduleWithFixedDelay(new ScheduleDelayJob(), 2, 2, TimeUnit.SECONDS);
		
	}
}

The following thread is scheduled to run 2 seconds after completion of the incumbent thread. Here’s the test run output:

2011-05-13 at 17:27:16 Starting run.
2011-05-13 at 17:27:17 Ending run.
2011-05-13 at 17:27:19 Starting run.
2011-05-13 at 17:27:21 Ending run.
2011-05-13 at 17:27:23 Starting run.
2011-05-13 at 17:27:26 Ending run.
2011-05-13 at 17:27:28 Starting run.
2011-05-13 at 17:27:32 Ending run.
2011-05-13 at 17:27:34 Starting run.
2011-05-13 at 17:27:39 Ending run.
2011-05-13 at 17:27:41 Starting run.
:
:
:

Note that the difference between “Starting Run” and “Ending Run” time stamps is increasing incremently by 1 second and that new thread execution is starting exactly 2 seconds after completion of the incumbent thread run.

Finally let’s move on to ExecutorCompletionService. To understand the significance of this class, let’s use a real life scenario. Consider a search engine, a user types in a word to search, the engine queries its database and retrieves matches and displays the end results. Now to speed up this match retrieval process, let’s say that instead of querying a single large database, the engine queries hundreds of small databases. To acheive this in an optimum fashion, instead of one thread running a sequential query on each database, it would make sense to parallelise the individual database query process and consolidate the results sequentially. That is precisely what ExecutorCompletionService endeavors to achieve.

Let’s create SearchFragmentResult class which replicates the individual database search thread. The
SearchFragmentResult class implements Callable interface and is expected to return an integer value representing number of matches. Here’s the source code of the SearchFragmentResult class.

package com.concurrency.exec.comp;

import java.util.concurrent.Callable;

import com.concurrency.utils.ConcurrencyUtils;

public class SearchResultFragment implements Callable<Integer> {

	private boolean throwException = false;
	private int delayValue = 0;
	
	public SearchResultFragment(int delay) {
		this.delayValue = delay;
	}
	
	public SearchResultFragment(int delay, boolean exceptionFlag) {
		this.throwException = exceptionFlag;
		this.delayValue = delay;
	}

	@Override
	public Integer call() throws Exception {
		System.out.println(ConcurrencyUtils.retrieveCurrentDate() + 
			": Starting " + ConcurrencyUtils.getShortThreadInfo());
		if (this.throwException) {
			throw new RuntimeException("Check exception handling.");
		}
		int val = 0;
		if (this.delayValue > 5) {
			val = 10 - this.delayValue;
		} else {
			val = this.delayValue*2;
		}
		Thread.sleep(val * 1000);
		System.out.println(ConcurrencyUtils.retrieveCurrentDate() + 
				": Completing " + ConcurrencyUtils.getShortThreadInfo());
		return this.delayValue;
	}

}

The SearchFragmentResult has two overloaded constructor implementations, one accepting a delay value as input and the other accepting an exception flag value as input along with delay value. The boolean flag is used to inform the class to throw RuntimeException during its thread run. The delay value puts the thread to sleep for a computed duration time. This is just to simulate real life behavior of response time differences. Logic has been added in the run method implementation to ensure varied sleep durations.

Now let’s move on to the test class ExecutorCompletionSvcTest. Refer the source code below:

package com.concurrency.exec.comp.test;

import java.util.ArrayList;
import java.util.List;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.ExecutorCompletionService;
import java.util.concurrent.ExecutorService;
import java.util.concurrent.Executors;
import java.util.concurrent.Future;

import com.concurrency.exec.comp.SearchResultFragment;

public class ExecutorCompletionSvcTest {

	public static void main(String[] args) {
		ExecutorService svc = Executors.newFixedThreadPool(2);
		
		ExecutorCompletionService<Integer> compSvc 
			= new ExecutorCompletionService<Integer>(svc);
		
		List<SearchResultFragment> inputs = new ArrayList<SearchResultFragment>();
		for (int i=0; i<10; i++){
			SearchResultFragment frag = new SearchResultFragment(i);
			inputs.add(frag);
		}
		
		List<Future<Integer>> results = new ArrayList<Future<Integer>>();
		for (SearchResultFragment searchResultFragment : inputs) {
			Future<Integer> future = compSvc.submit(searchResultFragment);
			results.add(future);
		}
		System.out.println("Done submitting all requests!");
		
		boolean notDone = true;
		int result = 0;
		
		while(notDone) {
			boolean status = false;
			for (Future<Integer> future : results) {
				if (!future.isDone()) {
					status = true;
				}
			}
			if (!status) {
				notDone = false;
			} else {
				try {
					Thread.sleep(2000);
				} catch (InterruptedException e) {
					e.printStackTrace();
				}
			}
		}
		
		for (Future<Integer> future : results) {
			int interimVal = 0;
			try {
				interimVal = future.get();
			} catch (InterruptedException e) {
				e.printStackTrace();
			} catch (ExecutionException e) {
				e.printStackTrace();
			}
			System.out.println("Interim Val: " + interimVal); 
			result += interimVal;

		}
		System.out.println("Result Value: " + result);
		svc.shutdown();
	}
}

The test code spawns 10 threads. These threads are submitted to ExecutorCompletionService, refer line 29 in the code. The service processes them and returns the match results as integer value. The value are returned back by the individual thread using the Future interface, refer line . The Future’s state is checked to validate if the processing is complete. This is achieved by invoking Future’s isDone() method, refer line . If completed, the value is retrieved using the get() method. The returned values are added to get the total match count. Here’s the test class run output:

Done submitting all requests!
2011-05-13 at 18:33:56: Starting Thread Id: 8, Name: pool-1-thread-1, Group: main

2011-05-13 at 18:33:56: Starting Thread Id: 9, Name: pool-1-thread-2, Group: main

2011-05-13 at 18:33:56: Completing Thread Id: 8, Name: pool-1-thread-1, Group: main

2011-05-13 at 18:33:56: Starting Thread Id: 8, Name: pool-1-thread-1, Group: main

2011-05-13 at 18:33:58: Completing Thread Id: 9, Name: pool-1-thread-2, Group: main

2011-05-13 at 18:33:58: Starting Thread Id: 9, Name: pool-1-thread-2, Group: main

2011-05-13 at 18:34:00: Completing Thread Id: 8, Name: pool-1-thread-1, Group: main

2011-05-13 at 18:34:00: Starting Thread Id: 8, Name: pool-1-thread-1, Group: main

2011-05-13 at 18:34:04: Completing Thread Id: 9, Name: pool-1-thread-2, Group: main

2011-05-13 at 18:34:04: Starting Thread Id: 9, Name: pool-1-thread-2, Group: main

2011-05-13 at 18:34:08: Completing Thread Id: 8, Name: pool-1-thread-1, Group: main

2011-05-13 at 18:34:08: Starting Thread Id: 8, Name: pool-1-thread-1, Group: main

2011-05-13 at 18:34:12: Completing Thread Id: 8, Name: pool-1-thread-1, Group: main

2011-05-13 at 18:34:12: Starting Thread Id: 8, Name: pool-1-thread-1, Group: main

2011-05-13 at 18:34:14: Completing Thread Id: 9, Name: pool-1-thread-2, Group: main

2011-05-13 at 18:34:14: Starting Thread Id: 9, Name: pool-1-thread-2, Group: main

2011-05-13 at 18:34:15: Completing Thread Id: 8, Name: pool-1-thread-1, Group: main

2011-05-13 at 18:34:15: Starting Thread Id: 8, Name: pool-1-thread-1, Group: main

2011-05-13 at 18:34:16: Completing Thread Id: 9, Name: pool-1-thread-2, Group: main

2011-05-13 at 18:34:16: Completing Thread Id: 8, Name: pool-1-thread-1, Group: main

Interim Val: 0
Interim Val: 1
Interim Val: 2
Interim Val: 3
Interim Val: 4
Interim Val: 5
Interim Val: 6
Interim Val: 7
Interim Val: 8
Interim Val: 9
Result Value: 45

The run output clearly shows that we created a thread pool of 2, which was honored and the threshold was not exceeded. Once all the threads completed their processing, individual values were sought and added together.

There is an alternative and albeit the right way of getting values from Future interfaces. Refer the source code for ExecutorCompletionSvc2Test.

package com.concurrency.exec.comp.test;

import java.util.ArrayList;
import java.util.List;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.ExecutorCompletionService;
import java.util.concurrent.ExecutorService;
import java.util.concurrent.Executors;
import java.util.concurrent.Future;

import com.concurrency.exec.comp.SearchResultFragment;

public class ExecutorCompletionSvc2Test {

	public static void main(String[] args) {
		ExecutorService svc = Executors.newFixedThreadPool(2);
		
		ExecutorCompletionService<Integer> compSvc 
			= new ExecutorCompletionService<Integer>(svc);
		
		List<SearchResultFragment> inputs = new ArrayList<SearchResultFragment>();
		for (int i=0; i<10; i++){
			SearchResultFragment frag = new SearchResultFragment(i);
			inputs.add(frag);
		}
		
		List<Future<Integer>> results = new ArrayList<Future<Integer>>();
		for (SearchResultFragment searchResultFragment : inputs) {
			Future<Integer> future = compSvc.submit(searchResultFragment);
			results.add(future);
		}
		System.out.println("Done submitting all requests!");
		
		int result = 0;
		int counter = 0;
		
		while(counter != 10) {
			try {
				Future<Integer> response = compSvc.take();
				try {
					int interimVal = response.get();
					result += interimVal;
				} catch (ExecutionException e) {
					e.printStackTrace();
				}
			} catch (InterruptedException e) {
				e.printStackTrace();
			}
			counter++;
		}
		
		System.out.println("Result Value: " + result);
		svc.shutdown();
	}
}

Here we use the take() method on ExecutorCompletionService to retrieve the Future reference of the currently completed thread, refer line 39.

So now what happens if an exception is thrown? Refer the source code of two test classes

ExecutorCompletionSvcExceptionTest and ExecutorCompletionSvcException2Test. ExecutorCompletionSvcException2Test is the right way to do things.

package com.concurrency.exec.comp.test;

import java.util.ArrayList;
import java.util.List;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.ExecutorCompletionService;
import java.util.concurrent.ExecutorService;
import java.util.concurrent.Executors;
import java.util.concurrent.Future;

import com.concurrency.exec.comp.SearchResultFragment;

public class ExecutorCompletionSvcExceptionTest {

	public static void main(String[] args) {
		ExecutorService svc = Executors.newFixedThreadPool(2);
		
		ExecutorCompletionService<Integer> compSvc 
			= new ExecutorCompletionService<Integer>(svc);
		
		List<SearchResultFragment> inputs = new ArrayList<SearchResultFragment>();
		for (int i=0; i<10; i++){
			SearchResultFragment frag = null;
			if (i == 5) {
				frag = new SearchResultFragment(i, true);
			} else {
				frag = new SearchResultFragment(i);
			}
			inputs.add(frag);
		}
		
		List<Future<Integer>> results = new ArrayList<Future<Integer>>();

		for (SearchResultFragment searchResultFragment : inputs) {
			Future<Integer> future = compSvc.submit(searchResultFragment);
			results.add(future);
		}
		System.out.println("Done submitting all requests!");
		boolean notDone = true;
		int result = 0;
		
		while(notDone) {
			boolean status = false;
			for (Future<Integer> future : results) {
				if (!future.isDone()) {
					status = true;
				}
			}
			if (!status) {
				notDone = false;
			} else {
				try {
					Thread.sleep(2000);
				} catch (InterruptedException e) {
					e.printStackTrace();
				}
			}
		}
		
		for (Future<Integer> future : results) {
			int interimVal = 11;
			try {
				interimVal = future.get();
				System.out.println("Interim Val: " + interimVal); 
				result += interimVal;

			} catch (InterruptedException e) {
				e.printStackTrace();
			} catch (ExecutionException e) {
				System.out.println("Execution Val: " + interimVal);
				e.printStackTrace();
			}

		}
		System.out.println("Result Value: " + result);
		svc.shutdown();
	}
}

package com.concurrency.exec.comp.test;

import java.util.ArrayList;
import java.util.List;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.ExecutorCompletionService;
import java.util.concurrent.ExecutorService;
import java.util.concurrent.Executors;
import java.util.concurrent.Future;

import com.concurrency.exec.comp.SearchResultFragment;

public class ExecutorCompletionSvcException2Test {

	public static void main(String[] args) {
		ExecutorService svc = Executors.newFixedThreadPool(2);
		
		ExecutorCompletionService<Integer> compSvc 
			= new ExecutorCompletionService<Integer>(svc);
		
		List<SearchResultFragment> inputs = new ArrayList<SearchResultFragment>();
		for (int i=0; i<10; i++){
			SearchResultFragment frag = null;
			if (i == 5) {
				frag = new SearchResultFragment(i, true);
			} else {
				frag = new SearchResultFragment(i);
			}
			inputs.add(frag);
		}
		
		List<Future<Integer>> results = new ArrayList<Future<Integer>>();

		for (SearchResultFragment searchResultFragment : inputs) {
			Future<Integer> future = compSvc.submit(searchResultFragment);
			results.add(future);
		}
		System.out.println("Done submitting all requests!");
		
		int result = 0;
		int counter = 0;
		
		while(counter != 10) {
			try {
				Future<Integer> response = compSvc.take();
				try {
					int interimVal = response.get();
					result += interimVal;
				} catch (ExecutionException e) {
					e.printStackTrace();
				}
			} catch (InterruptedException e) {
				e.printStackTrace();
			}
			counter++;
		}
		
		System.out.println("Result Value: " + result);
		svc.shutdown();
	}
}

Here’s the run output:

Done submitting all requests!
2011-05-13 at 18:43:47: Starting Thread Id: 8, Name: pool-1-thread-1, Group: main

2011-05-13 at 18:43:47: Starting Thread Id: 9, Name: pool-1-thread-2, Group: main

2011-05-13 at 18:43:47: Completing Thread Id: 8, Name: pool-1-thread-1, Group: main

2011-05-13 at 18:43:47: Starting Thread Id: 8, Name: pool-1-thread-1, Group: main

2011-05-13 at 18:43:49: Completing Thread Id: 9, Name: pool-1-thread-2, Group: main

2011-05-13 at 18:43:49: Starting Thread Id: 9, Name: pool-1-thread-2, Group: main

2011-05-13 at 18:43:51: Completing Thread Id: 8, Name: pool-1-thread-1, Group: main

2011-05-13 at 18:43:51: Starting Thread Id: 8, Name: pool-1-thread-1, Group: main

2011-05-13 at 18:43:55: Completing Thread Id: 9, Name: pool-1-thread-2, Group: main

2011-05-13 at 18:43:55: Starting Thread Id: 9, Name: pool-1-thread-2, Group: main

2011-05-13 at 18:43:55: Starting Thread Id: 9, Name: pool-1-thread-2, Group: main

2011-05-13 at 18:43:59: Completing Thread Id: 9, Name: pool-1-thread-2, Group: main

2011-05-13 at 18:43:59: Completing Thread Id: 8, Name: pool-1-thread-1, Group: main

2011-05-13 at 18:43:59: Starting Thread Id: 9, Name: pool-1-thread-2, Group: main

2011-05-13 at 18:43:59: Starting Thread Id: 8, Name: pool-1-thread-1, Group: main

2011-05-13 at 18:44:01: Completing Thread Id: 8, Name: pool-1-thread-1, Group: main

2011-05-13 at 18:44:01: Starting Thread Id: 8, Name: pool-1-thread-1, Group: main

2011-05-13 at 18:44:02: Completing Thread Id: 9, Name: pool-1-thread-2, Group: main

2011-05-13 at 18:44:02: Completing Thread Id: 8, Name: pool-1-thread-1, Group: main

Interim Val: 0
Interim Val: 1
Interim Val: 2
Interim Val: 3
Interim Val: 4
Execution Val: 11
java.util.concurrent.ExecutionException: java.lang.RuntimeException: Check exception handling.
	at java.util.concurrent.FutureTask$Sync.innerGet(Unknown Source)
	at java.util.concurrent.FutureTask.get(Unknown Source)
	at com.concurrency.exec.comp.test.ExecutorCompletionSvcExceptionTest.main

(ExecutorCompletionSvcExceptionTest.java:63)
Caused by: java.lang.RuntimeException: Check exception handling.
	at com.concurrency.exec.comp.SearchResultFragment.call(SearchResultFragment.java:26)
	at com.concurrency.exec.comp.SearchResultFragment.call(SearchResultFragment.java:1)
	at java.util.concurrent.FutureTask$Sync.innerRun(Unknown Source)
	at java.util.concurrent.FutureTask.run(Unknown Source)
	at java.util.concurrent.Executors$RunnableAdapter.call(Unknown Source)
	at java.util.concurrent.FutureTask$Sync.innerRun(Unknown Source)
	at java.util.concurrent.FutureTask.run(Unknown Source)
	at java.util.concurrent.ThreadPoolExecutor$Worker.runTask(Unknown Source)
	at java.util.concurrent.ThreadPoolExecutor$Worker.run(Unknown Source)
	at java.lang.Thread.run(Unknown Source)
Interim Val: 6
Interim Val: 7
Interim Val: 8
Interim Val: 9
Result Value: 40

As long as the main thread handles the exception, we lose only that worker thread’s computational value, the rest work fine and remain uninterrupted. As a devloper one might need to consider this possibility and design code accordingly.

That’s all for the moment. Kunal, I hope this helps.

All IT applications are developed with the end goal of addressing concern(s) or business requirement(s). Object oriented programming paradigm assists modularization of concerns. Modularization facilitates reuse and improves code maintenability. However there are certain concerns like security, transactions, logging, auditing etc which pervade the entire system and are essentially cross cutting. Implementing these concerns in the conventional fashion i.e. modular coding will be lead to code scattering all over the application. We need a completely different programming paradigm to address this issue. Aspect Oriented Programming (AOP) is the very paradigm for implementing such cross cutting concerns.

Before we begin on AOP and the breadth of support Spring framework provides to AOP, let us first familiarize ourselves with some terms commonly associated with AOP.

Advice: Advice is the additional code which is applied to existing code base. For example, in case we are interested in logging the processing time for every method execution, we need to add code at the start and completion of method execution, this additional code is advice.

Join point: Join point represents a particular point during the program execution. Examples of join points are method call, method execution, object instantiation, constructor execution, field references, exception handler etc. Note Spring AOP only supports method execution, for other join points use AspectJ.

Pointcut: Pointcut is the point of execution when the advice needs to be applied to a join point because the join point satisfies a certain condition for e.g. method name adheres to getter method format etc. For example consider we have a class with methods named getName, getPhoneNumber and calculate. Here all the three method executions represent join points; on the other hand we can define a pointcut for method calculate and apply advice for the same.

Aspect: The combination of advice and pointcut is an aspect.

Introduction: Introduction is addition of new methods or fields.

Target Object: Object which is adviced by one or more aspects. It is also called advised object.

AOP Proxy: A proxy created by AOP framework to implement advised contracts. In Spring AOP proxy is implemented using either JDK dynamic proxy or CGLIB proxy. If the target object implements an interface(s) that exposes the required methods, Spring will use the JDK’s java.lang.reflect.Proxy class. This class allows Spring to dynamically generate a new class that implements the necessary interfaces, weave in any advice, and proxy any calls to these interfaces to the target class. If the target class does not implement an interface, Spring uses the CGLIB library to generate a subclass for the target class. When creating this subclass, Spring weaves in advice and delegates calls to the subclass to the target class.

Weaving: Incorporation of aspects in the code base is called weaving. Weaving can be done either at compile time, class load time or runtime. Spring AOP does weaving at runtime.

Spring AOP classifies advice into the following categories:

Before advice: Advice that executes before a join point, but which does not have the ability to prevent execution flow proceeding to the join point (unless it throws an exception).

After returning advice: Advice to be executed after a join point completes normally: for example, if a method returns without throwing an exception.

After throwing advice: Advice to be executed if a method exits by throwing an exception.

After (finally) advice: Advice to be executed regardless of the means by which a join point exits (normal or exceptional return).

Around advice: Advice that surrounds a join point such as a method invocation. This is the most powerful kind of advice. Around advice can perform custom behavior before and after the method invocation. It is also responsible for choosing whether to proceed to the join point or to shortcut the advised method execution by returning its own return value or throwing an exception.

Enough of theory let’s start coding. Spring Framework supports AOP using its own Spring AOP framework or the versatile AspectJ framework. The following tutorial intends use both options in turn highlighting the similarities and differences between the two.

First let’s look at AspectJ. To demonstrate the AOP capabilities I create simple Java class SampleObject with suitable attributes and methods. Here’s the source code of SampleObject class.

package com.spring.aop.aspectj;

public class SampleObject {

	public SampleObject() {

	}

	public static void test(){

	}

	public String run() {
		return "First Run";
	}

	public String run(String input){
		return input;
	}

	public void exceptionHandling(){
		throw new RuntimeException("Exception Handling");
	}

	public void exceptionHandling(Object o){
		throw new RuntimeException("Exception Handling Object");
	}

	public void handle(String input){
	}

	public void handle(Integer input){
	}

	public void handle(Object input){
	}

	public void doProcess(Object input) {

	}
}

To enhance SampleObject with AOP capabilities we define an additional Java class AOPObject. In this class we define pointcuts and advices; definition of pointcuts is done using annotations. Refer the following source code for AOPObject. An additional utility class AOPUtils’s source code is provided below.

package com.spring.aop.aspectj;

import org.aspectj.lang.JoinPoint;
import org.aspectj.lang.ProceedingJoinPoint;
import org.aspectj.lang.Signature;
import org.aspectj.lang.annotation.After;
import org.aspectj.lang.annotation.AfterReturning;
import org.aspectj.lang.annotation.AfterThrowing;
import org.aspectj.lang.annotation.Around;
import org.aspectj.lang.annotation.Aspect;
import org.aspectj.lang.annotation.Before;
import org.aspectj.lang.annotation.Pointcut;

import com.spring.aop.util.AOPUtils;

@Aspect
public class AOPObject {

	public AOPObject() {
		
	}

	public AOPObject(String input) {
		
	}

	@Pointcut("execution(* *.run(..))")
	public String marker() {
		return "";
	}
	
	@Pointcut("execution(* *.run(String))")
	public void markerNew() {
		
	}

	@Pointcut("execution(* *.exceptionHandling())")
	public void markerForException() {
		
	}
	
	@Before("marker(),markerNew()")
	public void log(JoinPoint joinPoint) {
		System.out.println("+++++++++++++++++++++++++++++++++++++++");
		System.out.println("Before invoking the method: " + joinPoint.toShortString());
		Object[] args = joinPoint.getArgs();
		if (args != null && args.length > 0) {
			System.out.println("Name: " + args[0]);
		}
		Signature signature = joinPoint.getSignature();
		System.out.println("Information: " + signature.toLongString());
		System.out.println("+++++++++++++++++++++++++++++++++++++++");
	}
	
	@AfterReturning(value="marker(), markerNew()",
		returning="val")
	public void logReturn(String val) {
		System.out.println("&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&");
		System.out.println("After returning from the run method.");
		System.out.println("Ret Val: " + val);
		System.out.println("&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&");
		
	}

	@AfterThrowing(value="markerForException()",
			throwing="t")
	public void logThrow(Throwable t) {
		System.out.println("^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^");
		System.out.println("Processing exceptional condition during run method execution.");
		System.out.println("Exception thrown is: " + t);
		System.out.println("^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^");
	}
	
	@After("marker(), markerNew()")
	public void logFinally(JoinPoint joinPoint) {
		System.out.println("!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!");
		AOPUtils.displayJoinPointDetails("Logging finally irrespective of method execution.", joinPoint);
		System.out.println("!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!");
	}
	
	@Around("markerNew()")
	public void logAround(ProceedingJoinPoint joinPoint) {
		System.out.println("#####Before method invokation.#####: " + joinPoint.toShortString());
		try {
			joinPoint.proceed();
		} catch (Throwable e) {
			e.printStackTrace();
		}
		System.out.println("#####After method invokation.#####: " + joinPoint.toShortString());
	}
	
	@Before("within(com.spring.aop.aspectj.Test)")
	public void withinMarker(JoinPoint joinPoint) {
		System.out.println("?????????????????????");
		System.out.println("Within Pointcut designator for Test class.");
		AOPUtils.displayJoinPointDetails("*.Test", joinPoint);
		System.out.println("?????????????????????");
	}
	
	@Before("this(com.spring.aop.aspectj.Test) && execution(* doProcess(..))")
	void thisMarker() {
		System.out.println("@@@@@@@@@@@@@@@@@@@");
		System.out.println("doProcess method of Test class is invoked.");
		System.out.println("@@@@@@@@@@@@@@@@@@@");
	}
	
	@Before("args(java.lang.String))")
	void argsMarker(JoinPoint joinPoint) {
		System.out.println("[][][][][][][][][][][][][]");
		AOPUtils.displayJoinPointDetails("Following Method with String argument invoked",
				joinPoint);
		System.out.println("[][][][][][][][][][][][][]");
	}
	
	@Before("this(com.spring.aop.aspectj.CollectionContainer))")
	void thisContainerMarker() {
		System.out.println("|||||||||||||||||||||||||||||||||");
		System.out.println("'this' pointcut is invoked.");
		System.out.println("|||||||||||||||||||||||||||||||||");
	}
	
	@Before("target(com.spring.aop.aspectj.CollectionContainer))")
	void targetContainerMarker() {
		System.out.println("<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<");
		System.out.println("'target' pointcut is invoked.");
		System.out.println("<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<");
	}

}

package com.spring.aop.util;

import org.aspectj.lang.JoinPoint;
import org.aspectj.lang.Signature;

public class AOPUtils {
	
	public static void displayJoinPointDetails(String appendMessage, JoinPoint joinPoint) {
		Signature sign = joinPoint.getSignature();
		System.out.println(appendMessage + " : " + sign.toLongString());
	}

}

The first thing to notice is at line number 16 of AOPObject. To specify that this class provides AOP capabilities, the class has been annotated with @Aspect annotation. Let us know move on to the pointcut declarations. Refer line numbers 27, 32 and 37.

	@Pointcut("execution(* *.run(..))")
	public String marker() {
		return "";
	}

	@Pointcut("execution(* *.run(String))")
	public void markerNew() {
		
	}

	@Pointcut("execution(* *.exceptionHandling())")
	public void markerForException() {
		
	}

We have declared three methods namely marker, markerNew and markerForException.

Each method is annotated with a specific pointcut expression. That expression defines a constraint or limits the join points on which the advice will be applied.

For example consider the first expression ‘execution(* *.run(..))’. The expression states that this pointcut
applies on the execution of all classes whose methods are named run and the point cut applies irrespective of the return type and the number of method arguments. The * immediately following the execution open bracket denotes return type, the subsequent * denotes all classes. The .. within the brackets denotes method with any argument(s).

In the second example, we are specifically mentioning that the pointcut selects all classes whose method name is run and accept String as an argument. The third example we are interested in all classes whose method name is exceptionHandling and accepts no arguments.

The method implementation defined below the pointcut has no significance beyond being a placeholder for the AOP implementation. These methods can have return type and can use the default/friendly access modifier without compromising on the AOP functionality.Now that we have identified the point cut let’s look at how we can apply advice on that point cut. For that look at the following implementation within the AOPObject source code, refer the code between the line number 42 and line number 89.

	@Before("marker(),markerNew()")
	public void log(JoinPoint joinPoint) {
		System.out.println("+++++++++++++++++++++++++++++++++++++++");
		System.out.println("Before invoking the method: " + joinPoint.toShortString());
		Object[] args = joinPoint.getArgs();
		if (args != null && args.length > 0) {
			System.out.println("Name: " + args[0]);
		}
		Signature signature = joinPoint.getSignature();
		System.out.println("Information: " + signature.toLongString());
		System.out.println("+++++++++++++++++++++++++++++++++++++++");
	}
	
	@AfterReturning(value="marker(), markerNew()",
		returning="val")
	public void logReturn(String val) {
		System.out.println("&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&");
		System.out.println("After returning from the run method.");
		System.out.println("Ret Val: " + val);
		System.out.println("&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&");
		
	}

	@AfterThrowing(value="markerForException()",
			throwing="t")
	public void logThrow(Throwable t) {
		System.out.println("^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^");
		System.out.println("Processing exceptional condition during run method execution.");
		System.out.println("Exception thrown is: " + t);
		System.out.println("^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^");
	}
	
	@After("marker(), markerNew()")
	public void logFinally(JoinPoint joinPoint) {
		System.out.println("!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!");
		AOPUtils.displayJoinPointDetails("Logging finally irrespective of method execution.", joinPoint);
		System.out.println("!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!");
	}
	
	@Around("markerNew()")
	public void logAround(ProceedingJoinPoint joinPoint) {
		System.out.println("#####Before method invokation.#####: " + joinPoint.toShortString());
		try {
			joinPoint.proceed();
		} catch (Throwable e) {
			e.printStackTrace();
		}
		System.out.println("#####After method invokation.#####: " + joinPoint.toShortString());
	}

We have earlier discussed the different advice types, we will apply them here to create the aspect. So let’s look at the first method log. The point cuts declared using the marker and markerNew method are combined with the before advice type in the log method. Refer the log method annotation.

@Before("marker(),markerNew()")

What this does is that before invocation of the methods defined by marker and markerNew point cuts, the
implementation of log method will execute. The log method can have no arguments or can have a single argument JoinPoint. Using the JoinPoint argument provides the developer with the ability to gathering metadata details around the method on whom the AOP is applied. In my current implementation I have highlighted some areas of information available like method arguments, method signature etc.

A method execution can return a void or a return value. In case developers are interested in intercepting the method invocation post execution, they can use the AfterReturning advice type. Refer the following code:

   	@AfterReturning(value="marker(), markerNew()",
		returning="val")
	public void logReturn(String val) {
		System.out.println("After returning from the run method.");
		System.out.println("Ret Val: " + val);
		
	}

In the annotation we use the value attribute to reference the pointcut and the returning attribute to provide a name for the return value. The method implementation uses the same return value name ‘val’ along with the appropriate class type.

In rare occasions the method implementation throw exceptions. In case developers need to intercept these
exceptions, they can use the AfterThrowing advice type. Refer line number of the AOPObject source. Ready handle to the thrown exception is provided via the throwing attribute.

 
	@AfterThrowing(value="markerForException()",
			throwing="t")
	public void logThrow(Throwable t) {
		System.out.println("Processing exceptional condition during run method execution.");
		System.out.println("Exception thrown is: " + t);
	}

Use the After advice type to do some advice processing during the finally block code run. Here’s the implementation.

	@After("marker(), markerNew()")
	public void logFinally() {
		System.out.println("Logging finally irrespective of method execution.");
	}
 

Lastly developers might be interested in getting information or implementing some aspect encompassing the method execution i.e. before and after, they can use the Around advice type. Refer the sample implementation in AOPObject line number 82.

	@Around("markerNew()")
	public void logAround(ProceedingJoinPoint joinPoint) {
		System.out.println("Before method invokation.");
		try {
			joinPoint.proceed();
		} catch (Throwable e) {
			e.printStackTrace();
		}
		System.out.println("After method invokation.");
	}

The source code joinPoint.proceed in line number in the source code above controls the execution of method. The developer is free to write custom program before and after this code. Unlike using the JoinPoint class we are using ProceedingJoinPoint class which provides access to the proceed method.

To understand all that has been explained so far let’s create a test class AOPTest1. The source code of the class is as below:

package com.spring.test;

import org.springframework.context.ConfigurableApplicationContext;
import org.springframework.context.support.ClassPathXmlApplicationContext;

import com.spring.aop.aspectj.SampleObject;

public class AOPTest1 {

	public static void main(String[] args) {
				
		ConfigurableApplicationContext ctx 
			= new ClassPathXmlApplicationContext (new String[] {"aop1.xml"});

		SampleObject obj = (SampleObject)ctx.getBean("obj");
		System.out.println("{}{}{}{}{}{}{}{}{}{}{}{}{}{}");
		obj.run();
		System.out.println("{}{}{}{}{}{}{}{}{}{}{}{}{}{}");
		obj.run("Testing....");
		System.out.println("{}{}{}{}{}{}{}{}{}{}{}{}{}{}");
		obj.exceptionHandling();
		System.out.println("{}{}{}{}{}{}{}{}{}{}{}{}{}{}");
	}
}

Here’s the Spring configuration file.

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns:aop="http://www.springframework.org/schema/aop"
       xsi:schemaLocation="http://www.springframework.org/schema/beans
           http://www.springframework.org/schema/beans/spring-beans-3.0.xsd
           http://www.springframework.org/schema/aop 
           http://www.springframework.org/schema/aop/spring-aop-3.0.xsd">

	<bean id="obj" class="com.spring.aop.aspectj.SampleObject" />
	<bean id="aopObj" class="com.spring.aop.aspectj.AOPObject" />
	
	<aop:aspectj-autoproxy />		
</beans>

Running the test class generates the following output:

{}{}{}{}{}{}{}{}{}{}{}{}{}{}
+++++++++++++++++++++++++++++++++++++++
Before invoking the method: execution(SampleObject.run())
Information: public java.lang.String com.spring.aop.aspectj.SampleObject.run()
+++++++++++++++++++++++++++++++++++++++
&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&
After returning from the run method.
Ret Val: First Run
&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
Logging finally irrespective of method execution. : public java.lang.String 

com.spring.aop.aspectj.SampleObject.run()
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
{}{}{}{}{}{}{}{}{}{}{}{}{}{}
#####Before method invokation.#####: execution(SampleObject.run(..))
[][][][][][][][][][][][][]
Following Method with String argument invoked : public java.lang.String com.spring.aop.aspectj.SampleObject.run
(java.lang.String)
[][][][][][][][][][][][][]
+++++++++++++++++++++++++++++++++++++++
Before invoking the method: execution(SampleObject.run(..))
Name: Testing....
Information: public java.lang.String com.spring.aop.aspectj.SampleObject.run(java.lang.String)
+++++++++++++++++++++++++++++++++++++++
&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&
After returning from the run method.
Ret Val: Testing....
&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
Logging finally irrespective of method execution. : public java.lang.String 
com.spring.aop.aspectj.SampleObject.run(java.lang.String)
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
#####After method invokation.#####: execution(SampleObject.run(..))
{}{}{}{}{}{}{}{}{}{}{}{}{}{}
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Processing exceptional condition during run method execution.
Exception thrown is: java.lang.RuntimeException: Exception Handling
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Exception in thread "main" java.lang.RuntimeException: Exception Handling
	at com.spring.aop.aspectj.SampleObject.exceptionHandling(SampleObject.java:22)
	at com.spring.aop.aspectj.SampleObject$$FastClassByCGLIB$$6d2e8fc5.invoke(<generated>)
	at net.sf.cglib.proxy.MethodProxy.invoke(MethodProxy.java:191)
	at org.springframework.aop.framework.Cglib2AopProxy$CglibMethodInvocation.invokeJoinpoint
(Cglib2AopProxy.java:688)
	at org.springframework.aop.framework.ReflectiveMethodInvocation.proceed
(ReflectiveMethodInvocation.java:150)
	at org.springframework.aop.aspectj.AspectJAfterThrowingAdvice.invoke(AspectJAfterThrowingAdvice.java:55)
	at org.springframework.aop.framework.ReflectiveMethodInvocation.proceed
(ReflectiveMethodInvocation.java:172)
	at org.springframework.aop.interceptor.ExposeInvocationInterceptor.invoke
(ExposeInvocationInterceptor.java:89)
	at org.springframework.aop.framework.ReflectiveMethodInvocation.proceed
(ReflectiveMethodInvocation.java:172)
	at org.springframework.aop.framework.Cglib2AopProxy$DynamicAdvisedInterceptor.intercept
(Cglib2AopProxy.java:621)
	at com.spring.aop.aspectj.SampleObject$$EnhancerByCGLIB$$e056b02c.exceptionHandling(<generated>)
	at com.spring.test.AOPTest1.main(AOPTest1.java:21)

Only the relevant logging statements have been retained. Let’s break the output into individual runs.

First let’s look at the output for the following section of the test code:

		obj.run();

The output generated was

+++++++++++++++++++++++++++++++++++++++
Before invoking the method: execution(SampleObject.run())
Information: public java.lang.String com.spring.aop.aspectj.SampleObject.run()
+++++++++++++++++++++++++++++++++++++++
&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&
After returning from the run method.
Ret Val: First Run
&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
Logging finally irrespective of method execution. : public java.lang.String 
com.spring.aop.aspectj.SampleObject.run()
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

The first method to get invoked was the advice associated with the marker point cut. The next advice to get
executed is AfterReturning. And the last advice to get executed is the After advice.
Now let’s look at the second portion of the test code:

obj.run("Testing....");

#####Before method invokation.#####: execution(SampleObject.run(..))
[][][][][][][][][][][][][]
Following Method with String argument invoked : public java.lang.String com.spring.aop.aspectj.SampleObject.run
(java.lang.String)
[][][][][][][][][][][][][]
+++++++++++++++++++++++++++++++++++++++
Before invoking the method: execution(SampleObject.run(..))
Name: Testing....
Information: public java.lang.String com.spring.aop.aspectj.SampleObject.run(java.lang.String)
+++++++++++++++++++++++++++++++++++++++
&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&
After returning from the run method.
Ret Val: Testing....
&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
Logging finally irrespective of method execution. : public java.lang.String 
com.spring.aop.aspectj.SampleObject.run(java.lang.String)
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
#####After method invokation.#####: execution(SampleObject.run(..))

The first advice to be processed is Around advice. The logging statement within the logAround method is printed.

After invocation of the proceed method on the JoinPoint, the next advice to be processed is the args pointcut designator. We will cover this later on in the post. The next advice to be processed is the Before advice associated with the log method. On completion of the method execution the AfterReturning advice is triggered and the last advice to run is After advice.

Now let’s look at the output generated by running the following code:

	obj.exceptionHandling();

The output generated is follows:

{}{}{}{}{}{}{}{}{}{}{}{}{}{}
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Processing exceptional condition during run method execution.
Exception thrown is: java.lang.RuntimeException: Exception Handling
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Exception in thread "main" java.lang.RuntimeException: Exception Handling
	at com.spring.aop.aspectj.SampleObject.exceptionHandling(SampleObject.java:22)
	at com.spring.aop.aspectj.SampleObject$$FastClassByCGLIB$$6d2e8fc5.invoke(<generated>)
	at net.sf.cglib.proxy.MethodProxy.invoke(MethodProxy.java:191)
	at org.springframework.aop.framework.Cglib2AopProxy$CglibMethodInvocation.invokeJoinpoint
(Cglib2AopProxy.java:688)
	at org.springframework.aop.framework.ReflectiveMethodInvocation.proceed
(ReflectiveMethodInvocation.java:150)
	at org.springframework.aop.aspectj.AspectJAfterThrowingAdvice.invoke(AspectJAfterThrowingAdvice.java:55)
	at org.springframework.aop.framework.ReflectiveMethodInvocation.proceed
(ReflectiveMethodInvocation.java:172)
	at org.springframework.aop.interceptor.ExposeInvocationInterceptor.invoke
(ExposeInvocationInterceptor.java:89)
	at org.springframework.aop.framework.ReflectiveMethodInvocation.proceed
(ReflectiveMethodInvocation.java:172)
	at org.springframework.aop.framework.Cglib2AopProxy$DynamicAdvisedInterceptor.intercept
(Cglib2AopProxy.java:621)
	at com.spring.aop.aspectj.SampleObject$$EnhancerByCGLIB$$3ef22468.exceptionHandling(<generated>)
	at com.spring.test.AOPTest1.main(AOPTest1.java:21)

The AfterThrowing advice is invoked and no further processing is taking place due to the RuntimeException.
The examples used so far maintained a clear demarcation between the pointcut declaration and advice. However the framework does provide an alternative to combining the two together. Refer the following piece of code in the AOPObject class at line number 92.

	@Before("within(com.spring.aop.aspectj.Test)")
	public void withinMarker(JoinPoint joinPoint) {
		System.out.println("Within Pointcut designator for Test class.");
		AOPUtils.displayJoinPointDetails("*.Test", joinPoint);
	}

Here we are applying the before advice type and using the point cut designator within to state that any method executions within the Test class will be intercepted. The pointcut ‘within(com.spring.aop.aspectj.Test)’ is integrated with the advice annotation. For your ready reference I am enclosing the source code of AOPTest2.

package com.spring.test;

import org.springframework.context.ConfigurableApplicationContext;
import org.springframework.context.support.ClassPathXmlApplicationContext;

import com.spring.aop.aspectj.Test;

public class AOPTest2 {

	public static void main(String[] args) {
				
		ConfigurableApplicationContext ctx 
			= new ClassPathXmlApplicationContext (new String[] {"aop2.xml"});
		Test test = (Test)ctx.getBean("testObj");
		System.out.println("=====================================");
		test.invoke();
		System.out.println("=====================================");
		test.doProcess("");
		System.out.println("=====================================");
		
	}
}

aop2.xml source

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns:aop="http://www.springframework.org/schema/aop"
       xsi:schemaLocation="http://www.springframework.org/schema/beans
           http://www.springframework.org/schema/beans/spring-beans-3.0.xsd
           http://www.springframework.org/schema/aop 
           http://www.springframework.org/schema/aop/spring-aop-3.0.xsd">

	<bean id="aopObj" class="com.spring.aop.aspectj.AOPObject" />
	<bean id="testObj" class="com.spring.aop.aspectj.Test" />

	<aop:aspectj-autoproxy />		
</beans>

Let’s look at the other pointcut designators like this, target and args. Refer the source code within the line
numbers 100 and 127.

	@Before("this(com.spring.aop.aspectj.Test) && execution(* doProcess(..))")
	void thisMarker() {
		System.out.println("doProcess method of Test class is invoked.");
	}
	
	@Before("args(java.lang.String))")
	void argsMarker(JoinPoint joinPoint) {
		AOPUtils.displayJoinPointDetails("Following Method with String argument invoked",
				joinPoint);
	}

The ‘this’ designator is used in the context of the bean. If the bean type/class matches the name specified in the this expression, the pointcut condition is considered satisfied. Note that this checks the compile time type of the bean and not the runtime type. To validate with reference to runtime type you will need to use the ‘target’ designator.

The test class AOPTest2 run is displayed below:

=====================================
?????????????????????
Within Pointcut designator for Test class.
*.Test : public void com.spring.aop.aspectj.Test.invoke()
?????????????????????
=====================================
?????????????????????
Within Pointcut designator for Test class.
*.Test : public void com.spring.aop.aspectj.Test.doProcess(java.lang.String)
?????????????????????
@@@@@@@@@@@@@@@@@@@
doProcess method of Test class is invoked.
@@@@@@@@@@@@@@@@@@@
[][][][][][][][][][][][][]
Following Method with String argument invoked : public void com.spring.aop.aspectj.Test.doProcess(java.lang.String)
[][][][][][][][][][][][][]
=====================================

The output clearly shows that the invocation of invoke method causes the withinMarker method’s before advice to be triggered. Invocation of doProcess method triggers the withinMarker method’s advice is triggered for Test class and the thisMarker method associated with advice associated with Test class and execution of doProcess method is triggered.

Now let’s look at the following piece of code within AOPObject.

	@Before("args(java.lang.String))")
	void argsMarker(JoinPoint joinPoint) {
		System.out.println("[][][][][][][][][][][][][]");
		AOPUtils.displayJoinPointDetails("Following Method with String argument invoked",
				joinPoint);
		System.out.println("[][][][][][][][][][][][][]");
	}

The args pointcut designator checks the method arguments of all invoked methods which match to the specified method signature. The invocation of doProcess method of Test class triggers the advice associated with argsMarker method.

There is another pointcut designator called target which also accepts a class as its processing parameter. Let’s try and understand the difference between this and target pointcut designator. The basic difference between the two is that this designator evaluates the compile time class reference while target evaluates the runtime class reference. To understand this let’s use an example. Create a class Container and CollectionContainer. The source code of the two classes is shown below:

package com.spring.aop.aspectj;

public class Container {

	public void add(Object o){
		
	}
	
	public void remove(Object o){
		
	}		
}

package com.spring.aop.aspectj;


public class CollectionContainer extends Container {

}

The CollectionContainer bean is defined in the aop3.xml configuration file. Here’s the xml details.

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns:aop="http://www.springframework.org/schema/aop"
       xsi:schemaLocation="http://www.springframework.org/schema/beans
           http://www.springframework.org/schema/beans/spring-beans-3.0.xsd
           http://www.springframework.org/schema/aop 
           http://www.springframework.org/schema/aop/spring-aop-3.0.xsd">
	
	<bean id="obj" class="com.spring.aop.aspectj.SampleObject" />
	<bean id="aopObj" class="com.spring.aop.aspectj.AOPObject" />
	<bean id="container" class="com.spring.aop.aspectj.CollectionContainer" />
	
	<aop:aspectj-autoproxy />		
</beans>

Here’s the test code AOP3Test:

package com.spring.test;

import org.springframework.context.ConfigurableApplicationContext;
import org.springframework.context.support.ClassPathXmlApplicationContext;

import com.spring.aop.aspectj.Container;
import com.spring.aop.aspectj.SampleObject;

public class AOPTest3 {

	public static void main(String[] args) {
				
		ConfigurableApplicationContext ctx 
			= new ClassPathXmlApplicationContext (new String[] {"aop3.xml"});
		
		System.out.println("============================ Container");
		Container container = (Container)ctx.getBean("container");
		container.add(null);

		SampleObject obj = (SampleObject)ctx.getBean("obj");
		
		System.out.println("============================ handle(String)");
		obj.handle("");

		System.out.println("============================ handle(Object)");
		obj.handle(new Object());

		System.out.println("============================ doProcess(Object)");
		obj.doProcess(new Object());

		System.out.println("=============================== doProcess(String)");
		obj.doProcess("");
		
		System.out.println("============================ handle(Integer)");
		obj.handle(Integer.valueOf(1));
		
	}
}

We have created two new methods within the AOPObject class for Container related classes. The two methods are thisContainerMarker and targetContainerMarker. This first one uses ‘this’ designator for CollectionContainer and second one uses ‘target’ for CollectionContainer.

On running the test class let’s look at what the output the following piece of code generates:

		Container container = (Container)ctx.getBean("container");
		container.add(null);

============================ Container
<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
'target' pointcut is invoked.
<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<

Clearly only the target pointcut is invoked, this is because the class reference used in the test code is Container and the runtime reference is CollectionContainer. The subsequent test code in AOP3Test tests whether the args designator uses runtime or static reference for processing. The output generated is as follows:

============================ handle(String)
[][][][][][][][][][][][][]
Following Method with String argument invoked : public void com.spring.aop.aspectj.SampleObject.handle
(java.lang.String)
[][][][][][][][][][][][][]
============================ handle(Object)
============================ doProcess(Object)
=============================== doProcess(String)
[][][][][][][][][][][][][]
Following Method with String argument invoked : public void com.spring.aop.aspectj.SampleObject.doProcess
(java.lang.Object)
[][][][][][][][][][][][][]
============================ handle(Integer)

Clearly args designator works on the runtime parameter. It processes the method handle(java.lang.String) as a match as long as the runtime method argument is String. The same applies for doProcess even thought the method signature accepts Object. If the runtime argument is String it treats the method as a match.

Upto now we have looked at AspectJ capabilities available via the Spring Framework. AspectJ as a standalone AOP framework has far greater capabilities, however Spring has limited itself to implementing the most commonly used ones. We now move on to looking at what Spring AOP has to offer on its own.

Spring AOP provides a more simplified methodology of defining advice and pointcuts.Spring AOP provides an interface for each advice type. Here are the Spring AOP interfaces: MethodBeforeAdvice, AfterReturningAdvice, ThrowsAdvice, AfterAdvice and MethodInterceptor. Except for MethodInterceptor the rest of the interfaces names match the advice type. The MethodInterceptor replicates the Around advice. To gain a better understanding let’s implement a Java class AOPDiffObject. Here’s the source code for AOPDiffObject.

package com.spring.aop.spring;

import java.lang.reflect.Method;

import org.aopalliance.intercept.MethodInterceptor;
import org.aopalliance.intercept.MethodInvocation;
import org.springframework.aop.AfterAdvice;
import org.springframework.aop.AfterReturningAdvice;
import org.springframework.aop.MethodBeforeAdvice;
import org.springframework.aop.ThrowsAdvice;

public class AOPDiffObject implements MethodBeforeAdvice, AfterReturningAdvice, ThrowsAdvice,
		MethodInterceptor {

	public AOPDiffObject() {
		
	}

	//Implementation of MethodBeforeAdvice interface
	@Override
	public void before(Method method, Object[] args, Object target)
			throws Throwable {
		System.out.println("########## Before Advice Start ###########");
		System.out.println("Diff:Before invoking the run method.");
		if (args != null && args.length > 0) {
			System.out.println("Diff:Argument Value: " + args[0]);
		} else {
			System.out.println("Diff:Argument : None.");
		}
		System.out.println("########## Before Advice End ###########");
	}

	//Implementation of AfterReturningAdvice interface
	@Override
	public void afterReturning(Object returnVal, Method method, Object[] args,
			Object target) throws Throwable {
		System.out.println("########## After Returning Advice Start ###########");
		System.out.println("Diff:After returning from the run method.");
		System.out.println("Diff:Ret Val: " + returnVal);		
		System.out.println("########## After Returning Advice End ###########");
	}

	//ThrowsAdvice interface does define any methods but implementations are expected to implement
	//afterThrowing method as shown below
	public void afterThrowing(Throwable throwable) throws Throwable {
		System.out.println("########## After Throwing Advice Start ###########");
		System.out.println("Diff:Exception thrown.");
		System.out.println(throwable);
		System.out.println("########## After Throwing Advice End ###########");
	}

	//Implementation of MethodInterceptor interface
	@Override
	public Object invoke(MethodInvocation invocation) throws Throwable {
		System.out.println("########## Around Advice Start ###########");
		System.out.println("Diff:Before method invokation.");
		Object retValue = null;
		try {
			retValue = invocation.proceed();
		} catch (Throwable e) {
			e.printStackTrace();
		}
		System.out.println("Diff:After method invokation.");
		System.out.println("########## Around Advice End ###########");
		return retValue;
	}	
}

The before method realization implements the before Advice, similarly afterReturning method realization implements the After returning advice, afterThrowing method realization implements the After throwing advice and invoke method realization implements the Around advice. I was not able to find an implementation for After finally advice in Spring AOP.

Here’s the Spring configuration file.

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns:aop="http://www.springframework.org/schema/aop"
       xsi:schemaLocation="http://www.springframework.org/schema/beans
           http://www.springframework.org/schema/beans/spring-beans-3.0.xsd
           http://www.springframework.org/schema/aop 
           http://www.springframework.org/schema/aop/spring-aop-3.0.xsd">

	<bean id="obj" class="com.spring.aop.aspectj.SampleObject" />
	
	<bean id="aopObject" class="com.spring.aop.spring.AOPDiffObject" />
	<bean id="advisor" class="org.springframework.aop.aspectj.AspectJExpressionPointcutAdvisor">
		<property name="advice" ref="aopObject" />
		<property name="expression" value="execution(* *.run(..))" />
	</bean>
	<bean id="advisorTwo" class="org.springframework.aop.aspectj.AspectJExpressionPointcutAdvisor">
		<property name="advice" ref="aopObject" />
		<property name="expression" value="execution(* *.run(String))" />
	</bean>
	
	<aop:aspectj-autoproxy />		
</beans>

In the configuration xml refer the lines 16 and 20. Here we are defining the association between pointcuts and advices. These are used for implementing aspects in the implementation code. Spring AOP provides three methods for defining pointcut expressions. Perl regex, java regex and AspectJ. I am using AspectJ for its richness and also to maintain ease of mapping between understanding the AspectJ and Spring AOP implementation.

For academic reasons here’s the test class and output of the test run

package com.spring.test;

import org.springframework.context.ConfigurableApplicationContext;
import org.springframework.context.support.ClassPathXmlApplicationContext;

import com.spring.aop.aspectj.Container;
import com.spring.aop.aspectj.SampleObject;
import com.spring.aop.aspectj.Test;

public class AOPTest4 {

	public static void main(String[] args) {
				
		ConfigurableApplicationContext ctx 
			= new ClassPathXmlApplicationContext (new String[] {"aop4.xml"});
		SampleObject obj = (SampleObject)ctx.getBean("obj");
		obj.run();
		System.out.println("%%%%%%%%%%%%%%%%%%%%%%%%%%%%");
		obj.run("Testing....");
		
	}
}

19 Apr, 2011 1:53:37 PM org.springframework.context.support.AbstractApplicationContext prepareRefresh
INFO: Refreshing org.springframework.context.support.ClassPathXmlApplicationContext@32fb4f: startup date [Tue Apr 19 13:53:37 IST 2011]; root of context hierarchy
19 Apr, 2011 1:53:37 PM org.springframework.beans.factory.xml.XmlBeanDefinitionReader loadBeanDefinitions
INFO: Loading XML bean definitions from class path resource [aop4.xml]
19 Apr, 2011 1:53:37 PM org.springframework.beans.factory.support.DefaultListableBeanFactory preInstantiateSingletons
INFO: Pre-instantiating singletons in org.springframework.beans.factory.support.DefaultListableBeanFactory@544ec1: 
defining beans [obj,aopObject,advisor,advisorTwo,org.springframework.aop.config.internalAutoProxyCreator]; root of factory hierarchy
########## Around Advice Start ###########
Diff:Before method invokation.
########## Before Advice Start ###########
Diff:Before invoking the run method.
Diff:Argument : None.
########## Before Advice End ###########
########## After Returning Advice Start ###########
Diff:After returning from the run method.
Diff:Ret Val: First Run
########## After Returning Advice End ###########
Diff:After method invokation.
########## Around Advice End ###########
%%%%%%%%%%%%%%%%%%%%%%%%%%%%
########## Around Advice Start ###########
Diff:Before method invokation.
########## Before Advice Start ###########
Diff:Before invoking the run method.
Diff:Argument Value: Testing....
########## Before Advice End ###########
########## Around Advice Start ###########
Diff:Before method invokation.
########## Before Advice Start ###########
Diff:Before invoking the run method.
Diff:Argument Value: Testing....
########## Before Advice End ###########
########## After Returning Advice Start ###########
Diff:After returning from the run method.
Diff:Ret Val: Testing....
########## After Returning Advice End ###########
Diff:After method invokation.
########## Around Advice End ###########
########## After Returning Advice Start ###########
Diff:After returning from the run method.
Diff:Ret Val: Testing....
########## After Returning Advice End ###########
Diff:After method invokation.
########## Around Advice End ###########

That’s all from my end at the moment.

The Part I tutorial clearly explains the significance of the configuration file, how it achieves dependency injection and facilitates bean reuse. Now let’s look at other aspects of Spring Framework.

Spring Object Lifecycle

Objects created using Spring framework follow their own lifecycle; details of which will be explained hereon. Consider the following spring configuration file bean-lifecycle.xml.

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="http://www.springframework.org/schema/beans
           http://www.springframework.org/schema/beans/spring-beans-3.0.xsd"
           default-init-method="init" default-destroy-method="destroy">

  	<bean id="object" class="com.spring.bean.lifecycle.BeanObject">
  	</bean>
	
	<bean id="specialobject" class="com.spring.bean.lifecycle.SpecialBeanObject" 
		init-method="initObject" destroy-method="destroyObject">
	</bean>
		
</beans>

Here is the source code for the classes mentioned in the bean-lifecycle.xml file.

package com.spring.bean.lifecycle;

public class BeanObject {

	public void init() {
		System.out.println("Initialize");
	}

	public void destroy() {
		System.out.println("Destroy");
	}
}

package com.spring.bean.lifecycle;

public class SpecialBeanObject {

	public void initObject() {
		System.out.println("Initialize Object");
	}

	public void destroyObject() {
		System.out.println("Destroy Object");
	}
}

During an object creation it might be necessary for the developer to initialize the bean properly with default values or undertaking some specific housekeeping activities. Similarly before destroying the bean, the developer might need to clean up. Spring framework facilitates this by allowing definition of default-init-method and default-destroy-method within the beans element, refer line number 8. All beans whose method names matches the specified init or destroy method will participate in this lifecycle event. Alternatively Spring framework allows the definition of init and destroy method at bean level using init-method and destroy-method attribute within bean element, refer line number . To understand this refer the test class below:

package com.spring.test;

import org.springframework.context.ConfigurableApplicationContext;
import org.springframework.context.support.ClassPathXmlApplicationContext;

public class BeanLifeCycleTest {

	public static void main(String[] args) {

		ConfigurableApplicationContext ctx
			= new ClassPathXmlApplicationContext (new String[] {"bean-lifecycle.xml"});
		ctx.close();
	}
}

Note the destroy methods are invoked only if context.close() method is explicitly invoked as a part of the application program.

Spring framework defines a number of interfaces which will be invoked during the object’s lifecycle. To understand this consider the configuration file spring-bean-lifecycle.xml.

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="http://www.springframework.org/schema/beans
           http://www.springframework.org/schema/beans/spring-beans-3.0.xsd"
           default-init-method="initok" default-destroy-method="cleanok">

	<bean id="bean" class="com.spring.bean.lifecycle.SpringBeanLifecycle"
		init-method="initObj" destroy-method="cleanObj">
	</bean>
	
	<bean id="sample" class="com.spring.bean.lifecycle.SampleBean"/>		
</beans>

The source code of the Java beans configured in the xml is shown below:

package com.spring.bean.lifecycle;

public class SampleBean {

}

package com.spring.bean.lifecycle;

import org.springframework.beans.BeansException;
import org.springframework.beans.factory.BeanClassLoaderAware;
import org.springframework.beans.factory.BeanFactory;
import org.springframework.beans.factory.BeanFactoryAware;
import org.springframework.beans.factory.BeanNameAware;
import org.springframework.beans.factory.DisposableBean;
import org.springframework.beans.factory.InitializingBean;
import org.springframework.beans.factory.config.BeanPostProcessor;

public class SpringBeanLifecycle implements BeanNameAware, BeanClassLoaderAware, BeanFactoryAware,
	InitializingBean, DisposableBean, BeanPostProcessor {

	public void init() {
		System.out.println("Init bean");
	}

	public void clean() {
		System.out.println("Clean bean");
	}

	public void initObj() {
		System.out.println("Init bean Object");
	}

	public void cleanObj() {
		System.out.println("Clean bean Object");
	}

	@Override
	public void setBeanName(String name) {
		//Method implementation for BeanNameAware interface
		System.out.println("Getting bean name: " + name);
	}

	@Override
	public void setBeanClassLoader(ClassLoader classLoader) {
		//Method implementation for BeanClassLoaderAware interface
		System.out.println("Getting Bean Class loader.");
	}

	@Override
	public void setBeanFactory(BeanFactory fact) throws BeansException {
		//Method implementation for BeanFactoryAware interface
		System.out.println("Getting bean factory.");
	}

	@Override
	public void afterPropertiesSet() throws Exception {
		//Method implementation for InitializingBean interface
		System.out.println("Init");
	}

	@Override
	public void destroy() throws Exception {
		//Method implementation for DisposableBean interface
		System.out.println("Destory");
	}

	@Override
	public Object postProcessAfterInitialization(Object arg0, String arg1)
			throws BeansException {
		//Method implementation for BeanPostProcessor interface
		System.out.println("After init: Bean Name " + arg1);
		return arg0;
	}

	@Override
	public Object postProcessBeforeInitialization(Object arg0, String arg1)
			throws BeansException {
		//Method implementation for BeanPostProcessor interface
		System.out.println("Before init: Bean Name " + arg1);
		return arg0;
	}
}

Refer the SpringBeanLifecycle class. It contains two methods init and clean which are inline with the default-init-method and default-destroy-method defined in the beans element. The setBeanName method is an implementation of the BeanNameAware interface. The setBeanClassLoader method is an implementation of the BeanClassLoaderAware interface. The setBeanFactory method is an implementation of the BeanFactoryAware interface. The afterPropertiesSet method is an implementation of InitializingBean interface and destory method is an implementation of DisposableBean interface. The postProcessAfterInitialization and postProcessBeforeInitialization methods are implementation of the BeanPostProcessor interface.

Here’s the test class:

package com.spring.test;

import org.springframework.beans.factory.config.ConfigurableBeanFactory;
import org.springframework.beans.factory.xml.XmlBeanFactory;
import org.springframework.context.ApplicationContext;
import org.springframework.context.ConfigurableApplicationContext;
import org.springframework.context.support.ClassPathXmlApplicationContext;
import org.springframework.core.io.FileSystemResource;
import org.springframework.core.io.Resource;

public class SpringBeanLifeCycleTest {

	public static void main(String[] args) {

		/*Resource resource = new FileSystemResource("src/spring-bean-lifecycle.xml");
	    ConfigurableBeanFactory beanFactory = new XmlBeanFactory(resource);
	    beanFactory.addBeanPostProcessor(new SpringBeanPostProcessor());
	    Object bean = beanFactory.getBean("bean");
	    beanFactory.destroyBean("bean", bean);*/

		ConfigurableApplicationContext ctx
			= new ClassPathXmlApplicationContext (new String[] {"spring-bean-lifecycle.xml"});
		System.out.println("%%%%%%%%%%%%%%%%%%%%%%%%%%");
		ctx.getBean("bean");
		System.out.println("%%%%%%%%%%%%%%%%%%%%%%%%%%");
		ctx.close();
	}
}

Refer the commented code in the test class for an alternative way of retrieving a bean object.

Here’s the output of the test class run(only relevant log entries are considered):

Getting bean name: bean
Getting Bean Class loader.
Getting bean factory.
Init
Init bean Object
Before init: Bean Name sample
After init: Bean Name sample
%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%
Destory
Clean bean Object

The invocation order of the Spring bean is as below:

1. setBeanName method of BeanNameAware interface.
2. setBeanClassLoader method of BeanClassLoaderAware interface.
3. setBeanFactory method of BeanFactoryAware interface.
4. afterPropertiesSet method of InitializingBean interface.
5. init-method of bean element in the configuration xml.
6. postProcessBeforeInitialization method of BeanPostProcessor interface.
7. postProcessAfterInitialization method of BeanPostProcessor interface.
8. destroy method of DisposableBean interface.
9. destroy-method of bean element in the configuration xml

The default-*-method attributes defined in the beans element is overridden by the bean level definitions of init-method and destroy-method. Note that the BeanPostProcessor interface implementation does not act on SpringBeanLifecycle class but monitors the SampleBean class.

Autowiring

Up to now we have adopted the approach of creating a configuration file. Defining a bean, its default value and collaborators within the configuration file. The cross references between beans were explicitly defined within the configuration. However Spring also provides an alternative where it autowires or automatically selects the appropriate reference within the configuration file. Spring Framework supports the following autowiring modes:

1. No autowiring
2. By Name
3. By Type
4. Constructor

Earlier versions of Spring framework used to support an autodetect mode which is no longer supported in Spring 3.
The first mode ‘no autowiring’ is essentially what we have done so far. Actually defined the references between the various bean definitions in the configuration file.

The next one is By Name. This autowiring type tries to match a bean in the container whose id or name matches the name of the property. If no match is found, the property remains unwired. To understand this autowiring mode better let’s use an example. Consider the following classes Car, CarModel and Engine. Their source code is below:

package com.spring.autowire;

public class Car {

	private String makerName = null;
	private String model     = null;
	private String name      = null;

	private Engine engine    = null;

	public String getMakerName() {
		return makerName;
	}

	public void setMakerName(String makerName) {
		this.makerName = makerName;
	}

	public String getModel() {
		return model;
	}

	public void setModel(String model) {
		this.model = model;
	}

	public String getName() {
		return name;
	}

	public void setName(String name) {
		this.name = name;
	}

	public Engine getEngine() {
		return engine;
	}

	public void setEngine(Engine engine) {
		this.engine = engine;
	}

	@Override
	public String toString() {
		StringBuilder sb = new StringBuilder();
		sb.append("Car ###############");
		sb.append("\n");
		sb.append("Maker name: ");
		sb.append(this.makerName);
		sb.append("\n");
		sb.append("Name: ");
		sb.append(this.name);
		sb.append("\n");
		sb.append("Model: ");
		sb.append(this.model);
		sb.append("\n");
		if (this.engine != null) {
			sb.append(this.engine.toString());
		}
		sb.append("################");
		sb.append("\n");

		return sb.toString();
	}

}

package com.spring.autowire;

public class Engine {

	private String name  = null;
	private String model = null;
	private int capacity = 0;

	public String getName() {
		return name;
	}
	public void setName(String name) {
		this.name = name;
	}
	public String getModel() {
		return model;
	}
	public void setModel(String model) {
		this.model = model;
	}
	public int getCapacity() {
		return capacity;
	}
	public void setCapacity(int capacity) {
		this.capacity = capacity;
	}

	@Override
	public String toString(){
		StringBuilder sb = new StringBuilder();
		sb.append("Engine ***************");
		sb.append("\n");
		sb.append("Name: ");
		sb.append(this.name);
		sb.append("\n");
		sb.append("Model: ");
		sb.append(this.model);
		sb.append("\n");
		sb.append("Capacity: ");
		sb.append(this.capacity);
		sb.append("\n");
		sb.append("**********************");
		sb.append("\n");

		return sb.toString();
	}
}

Create the following configuration xml beans-autowire.xml.

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="http://www.springframework.org/schema/beans
           http://www.springframework.org/schema/beans/spring-beans-3.0.xsd"
           default-autowire="byName">

	<bean id="makerName" class="java.lang.String" factory-method="valueOf">
		<constructor-arg value="Toyota" />
	</bean>

	<bean name="name" class="java.lang.String" factory-method="valueOf">
		<constructor-arg value="Camry" />
	</bean>

	<bean name="model" class="java.lang.String" factory-method="valueOf">
		<constructor-arg value="2011" />
	</bean>

	<bean name="capacity" class="java.lang.Integer" factory-method="valueOf">
		<constructor-arg value="2500" />
	</bean>

  	<bean id="camry" class="com.spring.autowire.Car">
  		<property name="makerName" ref="makerName" />
  		<property name="name" ref="name" />
  		<property name="model" ref="model" />
  	</bean>

  	<bean id="engine" class="com.spring.autowire.Engine">
  		<property name="name" ref="name" />
  		<property name="model" ref="model" />
  		<property name="capacity" ref="capacity" />
  	</bean>
	<!-- Please also note that it is not currently possible to autowire so-called simple properties 
		such as primitives, Strings, and Classes (and arrays of such simple properties)-->
</beans>

Refer line number 8. Here within the beans element tag the attribute default-autowire is set to ‘byName’. This informs the configuration to use byName mode for autowiring. Here’s the test class to validate:

package com.spring.test;

import org.springframework.context.ConfigurableApplicationContext;
import org.springframework.context.support.ClassPathXmlApplicationContext;

import com.spring.autowire.Car;

public class BeanAutowireTest {

	public static void main(String[] args) {

		ConfigurableApplicationContext ctx
			= new ClassPathXmlApplicationContext (new String[] {"beans-autowire.xml"});
		Car car = (Car)ctx.getBean("camry");
		System.out.println(car);
		ctx.close();
	}
}

On running the test class we observe that even though the xml did not define any explicit association between the Car’s engine property and Engine bean, due to autowiring the property has been automatically associated with the engine bean. This is because the property name within Car and bean id within the configuration xml is the same. Do note that we have explicitly wired the other primitive attributes like makerName, model etc. This is because simple attributes such as primitives, Strings and classes (and arrays of such simple properties) are not supported byName autowiring. This apparently is a feature!! An obvious limitation of byName autowiring type is that the id/name should match the property name. The developer will have to be careful in naming bean’s properties to ensure that there is no conflict. In a medium to large size project, this constraint could prove to be a serious limitation.

Moving on let’s look at autowiring byType mode. In this mode, the auto wiring is done by comparing the bean definition type and the type of the bean property. If both match, the property is autowired to the bean. Look at the following configuration xml beans-autowire-type.xml.

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="http://www.springframework.org/schema/beans
           http://www.springframework.org/schema/beans/spring-beans-3.0.xsd"
           default-autowire="byType">

	<bean id="makerName" class="java.lang.String" factory-method="valueOf">
		<constructor-arg value="Toyota" />
	</bean>

	<bean name="name" class="java.lang.String" factory-method="valueOf">
		<constructor-arg value="Camry" />
	</bean>

	<bean name="model" class="java.lang.String" factory-method="valueOf">
		<constructor-arg value="2011" />
	</bean>

	<bean name="capacity" class="java.lang.Integer" factory-method="valueOf">
		<constructor-arg value="2500" />
	</bean>

  	<bean id="camry" class="com.spring.autowire.Car">
  		<property name="makerName" ref="makerName" />
  		<property name="name" ref="name" />
  		<property name="model" ref="model" />
  	</bean>

  	<bean id="engine" class="com.spring.autowire.Engine">
  		<property name="name" ref="name" />
  		<property name="model" ref="model" />
  		<property name="capacity" ref="capacity" />
  	</bean>
	<!-- Please also note that it is not currently possible to autowire so-called simple properties 
		such as primitives, Strings, and Classes (and arrays of such simple properties)-->
</beans>

In the beans element declaration the attribute default-autowire value is changed to ‘byType’. Like byName, byType also does not support primitive or wrapper classes autowiring. For our example only wiring of the engine property of Car takes place using the byType autowiring mode. Here’s the test code for autowire byType.

package com.spring.test;

import org.springframework.context.ConfigurableApplicationContext;
import org.springframework.context.support.ClassPathXmlApplicationContext;

import com.spring.autowire.Car;

public class BeanAutowireTypeTest {

	public static void main(String[] args) {

		ConfigurableApplicationContext ctx
			= new ClassPathXmlApplicationContext (new String[] {"beans-autowire-type.xml"});
		Car car = (Car)ctx.getBean("camry");
		System.out.println(car);
		ctx.close();
	}

}

The final autowiring type is by constructor. It is similar to byType automode but applies to constructor arguments. If the constructor argument’s type matches the bean definition type, the constructor argument is autowired to bean. Refer the source code below of CarModel class.

package com.spring.autowire;

public class CarModel {

	private Engine engine = null;

	public CarModel(Engine engine) {
		this.engine = engine;
	}

	@Override
	public String toString() {
		StringBuilder sb = new StringBuilder();
		sb.append("Car Model ###############");
		sb.append("\n");
		if (this.engine != null) {
			sb.append(this.engine.toString());
		}
		sb.append("################");
		sb.append("\n");

		return sb.toString();
	}
}

The class defines a constructor with Engine as its argument. Refer to the configuration xml beans-autowire-constructor.xml

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="http://www.springframework.org/schema/beans
           http://www.springframework.org/schema/beans/spring-beans-3.0.xsd"
           default-autowire="constructor">

	<bean id="makerName" class="java.lang.String" factory-method="valueOf">
		<constructor-arg value="Toyota" />
	</bean>

	<bean name="name" class="java.lang.String" factory-method="valueOf">
		<constructor-arg value="Camry" />
	</bean>

	<bean name="model" class="java.lang.String" factory-method="valueOf">
		<constructor-arg value="2011" />
	</bean>

	<bean name="capacity" class="java.lang.Integer" factory-method="valueOf">
		<constructor-arg value="2500" />
	</bean>

  	<bean id="camry" class="com.spring.autowire.CarModel">
  	</bean>

  	<bean id="engine" class="com.spring.autowire.Engine">
  		<property name="name" ref="name" />
  		<property name="model" ref="model" />
  		<property name="capacity" ref="capacity" />
  	
  	</bean>
</beans>

The default-autowire attribute in the xml is changed to constructor. There is a bean with id ‘camry’ and type as CarModel. Using this autowiring mode, the engine bean is associated with the CarModel constructor argument. To validate refer the test class below:

package com.spring.test;

import org.springframework.context.ConfigurableApplicationContext;
import org.springframework.context.support.ClassPathXmlApplicationContext;

import com.spring.autowire.CarModel;

public class BeanAutowireConstructorTest {

	public static void main(String[] args) {

		ConfigurableApplicationContext ctx
			= new ClassPathXmlApplicationContext (new String[] {"beans-autowire-constructor.xml"});
		CarModel carModel = (CarModel)ctx.getBean("camry");
		System.out.println(carModel);
		ctx.close();
	}

}

Internationalization(i18n)

A common requirement of enterprise application is to support internationalization(i18n). Spring framework also supports internationalization. I have created three properties file namely text.properties, text_fr_FR.properties and text_en_GB.properties.

Contents of text.properties

firstname=Bill
lastname=Smith
greeting=Howdy

Contents of text_fr_FR.properties

firstname=Bill
lastname=Smith
greeting=bonjour

Contents of text_en_GB.properties

firstname=Bill
lastname=Smith
greeting=Hello

To achieve i18n, the following configuration xml i18n.xml is used.

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="http://www.springframework.org/schema/beans
           http://www.springframework.org/schema/beans/spring-beans-3.0.xsd">
 	
  	<bean id="messageSource"
		class="org.springframework.context.support.ResourceBundleMessageSource">
		<property name="basename">
			<value>text</value>
		</property>
	</bean>
</beans>

To define i18n configuration we create a bean with id ‘messageSource’ and provide property named ‘basename’. The value defined for the property basename is the property file name ‘text’. The extensions file such as text_fr_FR and text_en_GB need not be mentioned. To gain access to the property file values refer the test code below:

package com.spring.test;

import java.util.Locale;

import org.springframework.context.ConfigurableApplicationContext;
import org.springframework.context.support.ClassPathXmlApplicationContext;

public class I18NTest {

	public static void main(String[] args) {
		ConfigurableApplicationContext ctx 
			= new ClassPathXmlApplicationContext (new String[] {"i18n.xml"});
		String firstName = ctx.getMessage("firstname", new Object[0], Locale.US);
		String lastName = ctx.getMessage("lastname", new Object[0], Locale.US);
		String greeting = ctx.getMessage("greeting", new Object[0], Locale.US);
		System.out.println("Message: " + greeting + " " + firstName + " " + lastName);

		firstName = ctx.getMessage("firstname", new Object[0], Locale.UK);
		lastName = ctx.getMessage("lastname", new Object[0], Locale.UK);
		greeting = ctx.getMessage("greeting", new Object[0], Locale.UK);
		System.out.println("Message: " + greeting + " " + firstName + " " + lastName);

		firstName = ctx.getMessage("firstname", new Object[0], Locale.FRANCE);
		lastName = ctx.getMessage("lastname", new Object[0], Locale.FRANCE);
		greeting = ctx.getMessage("greeting", new Object[0], Locale.FRANCE);
		System.out.println("Message: " + greeting + " " + firstName + " " + lastName);
		
	}

}

The Spring context object provides access to the property file values using the getMessage method. The test code to retrieve locale specific values is illustrated in the test code.

That’s all for the moment.