Running JBoss AS 7 on Amazon EC2

This is a quick set of steps to get JBoss AS 7 running on a SUSE Linux Enterprise Server 11 instance. These are not necessarily best practices, especially the firewall settings. But, if you want to quickly get started playing with JBoss, this article will save you a bit of hassle.

Step 1: First install JDK7. I couldn’t get a clean URL that I could use with curl to download the RPM directly from the EC2 instance. So, I had to first download the RPM from Oracle to my Windows desktop and upload it to my EC2 instance using SFTP. Then install the JDK:

rpm -Uvh jdk-7u5-linux-x64.rpm

Step 2: Then, install JBoss 7. This one is a bit easier. First, get the distribution using the curl command.

curl -o jboss7.1.zip \
http://download.jboss.org/jbossas/7.1/jboss-as-7.1.1.Final/jboss-as-7.1.1.Final.zip

Then just unzip the file.

unzip jboss7.1.zip

Step 3: This step is optional. I was using a micro instance, so the memory is really low. I had to tweak Java’s memory setting to get JBoss to start. This may not be necessary, if you have more memory available. Open <JBOSS>/bin/standalone.conf. Drastically lower the memory settings as shown in bold face.

JAVA_OPTS="-Xms64m -Xmx86m -XX:MaxPermSize=64m -Djava.net.preferIPv4Stack=true ...

As I said, this sets the memory limits to ridiculously low values and are useless to run a real web site.

If system runs out of memory, you may see this error message, when you start JBoss.

# There is insufficient memory for the Java Runtime Environment to continue. 
# Native memory allocation (malloc) failed to allocate 128 bytes for CHeapObj-nw

Step 4: Now, we have to play with the firewall settings. First, we have to configure JBoss to use the Ethernet interface to listen for incoming requests. Without that, you will be able to use the applications from within the instance only. The name of the Ethernet interface should be eth0. If you are not sure, just run the ifconfig command to find out. Then open <JBOSS>/standalone/configuration/standalone.xml. Within the <interfaces> element, add a new <interface> element as follows:

<interfaces>
…
        <interface name="external">
                <nic name="eth0"/>
        </interface>
</interfaces>

Then, use the interface from various socket bindings.

<socket-binding name="management-http" interface="external" 
    port="${jboss.management.http.port:9990}"/>
<socket-binding name="management-https" interface="external" 
    port="${jboss.management.https.port:9443}"/>
<socket-binding name="ajp" interface="external" port="8009"/>
<socket-binding name="http" interface="external" port="8080"/>
<socket-binding name="https" interface="external" port="8443"/>

Caveat: In real life, you may not want to allow connection to the admin console from the Internet.

Step 5: Create a JBoss administrator user by running the <JBOSS>/bin/add-user.sh command. Just enter a user name and password, and accept all other defaults.

Step 6: Finally, for the security group of your EC2 instance, open up port 8080 and 9990.

Step 7: Start the server by running <JBOSS>/bin/standalone.sh.

Now, you should be able to use a web browser from your desktop and access http://EC2_HOSTNAME:8080. The admin console is at http://EC2_HOSTNAME:9990/console.

You can shutdown the server by running this from <JBOSS>/bin.

./jboss-cli.sh --connect command=:shutdown

You probably want the server to start when the EC2 instance boots up. JBoss 7.1 ships with an init.d script for a standalone system. This is located in <JBOSS>/bin/init.d/jboss-as-standalone.sh. But, frankly, I found the script to be plain strange. You can roll your own by following some of the ideas in this post.

Create a script called, say, jboss in /etc/init.d directory.

Then run tis command to configure the script as init.d script:

chkconfig --add jboss

Reboot the instance and make sure that JBoss server starts up.

Git Tutorial for Beginners Part I

I must admit, I am one of those who had their brains formatted by CVS. It was darn difficult to understand Git and its benefits. I figure there are many like me out there. This is why I decided to write a Git tutorial series from my view point. Also, I apply Git to a smaller scale project than say, Linux kernel with a massive number of developers.

My knowledge of Git is nowhere near being at an expert level. I’m sure I will say something that is stupid. So please bear this in mind in your comments. Please help me make this series better.

I found a few things really helpful when learning about Git:

• I found this book on Git very helpful. It’s completely free.
• Whether you are following this tutorial or reading the book above, always actually do the steps. Just reading about Git will get your brains confused really quickly. Actually doing the steps will help you a lot.
• The best way to learn about Git is to use the command line tools. IDEs like Xcode and Eclipse have some level of Git support. But, as a beginner, they really messed me up.

In Part I, we will focus on code committing. We will get to working with branches in future parts.

Please make sure that you have a working Git command line system before proceeding. The book mentioned above has clear steps on installation in Linux, Windows and Mac (I am using Mac to write these articles).

What is a Repository?

In CVS there is only one repository – the one that sits in the central server. Every developer has a working copy of the files in a local folder.

In Git, typically, each developer has a local repository. This is where code is committed frequently. Since this is a local repo, you don’t have to be super careful that the code works or even compiles:-). Basically, you are backing your work up periodically. In case of a bad mistake, you can always get things back from the local repo.

Once you are happy with the code, you can push the changes to a central repository. When pushing your code to the central repo, you can choose to include the history of every local commits. Or, better yet, you can compress all local commits into a single commit. This is better. Because, other developers don’t need to know about every little local commits you have done. We will get to this later.

Creating a Local Repository

There are two ways you can create a local repository:

1. Create a brand new repository for a new project. This is usually done only once in the life of a project.
2. For existing projects, create a clone of a remote repository in your local hard drive.

Let’s first learn to create a brand new local repository. Xcode and Eclipse provides ways to create a new local repo for any project. But, as I said, let’s not use the IDEs for this yet.

Create a folder structure for your project. If you are using Xcode or Eclipse, just create the project using the IDE tools.

Open a command prompt window and go to the root folder of the project. (Xcode creates many folders with similar sounding names. The root folder contains the PROJECT.xcodeproj folder. So, yeah, it’s really the root folder.)

Run this command to create a new local repository for the project.

git init

The repository is physically created in the .git folder within the root. If you regularly backup your hard drive, don’t forget to include that folder.

Now, let’s see how to create a local repo by cloning a remote one. This is something you need to do to contribute code to a project that already exists.

Using the command prompt, go to any folder. It should not be initialized using git init (which is only used to create a brand new repo). Then run the git clone command with the URL to the remote repo. For example, try this:

git clone git://github.com/bibhas2/ThreadControl.git

This will create a folder for the project within where you are right now. This folder will have the repository in it (in .git).

Committing Files

Commit is a multi step process. New or modified files are first added to a list of files to be committed. This is called staging. Then you do the commit. Also, as I said, commits are first done to a local repo. Changes are finally pushed to a remote repo.

This type of multi-stage commit process really helps developers experiment freely.

Let’s get started. Create a bunch of files in your project’s folder. If you are using Xcode or Eclipse, this is already done for you.

From the command prompt, use the git add command to add files to the staging area (list of files ready for commit). For example, running this command from the root folder will add all modified files to the staging area:

git add .

Alternatively, you can selectively add files or folders to commit list. If you specify a folder, all subfolders are recursively traversed and all files are added to the staging area.

git add file.c
git add src/

Note: Every time you modify a file, you will need to schedule it for commit using git add. This is nothing like the cvs add command. With git add, you are not adding a file to the repository. You are adding it to a list of files ready for commit.

If you have deleted a file, you can schedule that change for commit using git rm command.

git rm test.c

Before you go ahead and commit, you should probably see what exactly will be committed. This can be done using the git status command. A file can be in any one of these states:

1. A file was created, modified or deleted and has been staged for commit. Only these changes will be committed.
2. A file was modified or deleted but has not been staged for commit. These changes will not be committed.
3. A file has been created but has not been staged for commit. Git is not even tracking this file in anyway.

Let’s see an example git status output. You can run the command from any folder within the project. The output will be the same.

git status

A sample output will be:

# On branch master
# Changes to be committed:
# (use "git reset HEAD <file>..." to unstage)
#
# deleted: test.c
#
# Changes not staged for commit:
# (use "git add <file>..." to update what will be committed)
# (use "git checkout -- <file>..." to discard changes in working directory)
#
# modified: ../README
# modified: another.c
#
# Untracked files:
# (use "git add <file>..." to include in what will be committed)
#
# new.c

The file test.c was deleted and was scheduled for commit (using git rm). Only this change will be committed. Files README and another.c have been modified but have not been scheduled for commit. The file new.c was created but never scheduled for commit. Git is not tracking this file in any way.

Finally, to commit the changes, use the git commit command.

git commit
git commit -m "A commit message"

Carefully staging each modified file may be tedious. Especially, if you have made mass changes. In that case, do an auto staging using the -a switch.

git commit -a

This will automatically add all modified files to the staging area and remove deleted files prior to doing a commit.

Things to Consider

What gets staged is not so much a file but changes to a file. Consider the scenario:

1. You modify a file.
2. Stage the file for commit.
3. Make more changes to the file.
4. Commit the file. This will only commit the contents of the file as it was when it was staged.

Also, in CVS, a single repository stores many Eclipse or Xcode projects. They are called modules. You checkout individual modules as needed. In Git, each project has its own repository. If you have several projects that are closely tied together, it may be cumbersome to work with multiple different repositories. In that case, you can create a super-repository that will contain individual Xcode or Eclipse projects as subfolders. For example, let’s say that we have a Eclipse workspace with these folders:

.metadata – This is used by Eclipse. There is no need to store it in Git repo.
ProjectA – An Eclipse project
ProjectB – Another Eclipse project

You can create a single Git repo for the whole workspace. From the workspace folder, run:

git init
git add ProjectA
git add ProjectB

In addition, create a .gitignore file in the workspace folder to exclude the .metadata folder.

.metadata/   #Exclude this folder
*.class      #Exclude Java classes

 

C++ shared_ptr and STL Collections

In a previous post I introduced shared pointers as a way for automatic reference counting (ARC) in C++. This post will conclude the series by showing how to store shared pointers with STL containers like vector.

Let’s use the same MyClass class as the previous post.

class MyClass {
public:
	MyClass(){
		cout << "Creating MyClass object" << endl;
	}
	virtual ~MyClass(){
		cout << "Destroying MyClass object" << endl;
	}
	void method(){
		cout << "Called method of MyClass object" << endl;
	}
};

This shows how to store shared pointers in a vector.

#include <iostream>
#include <memory>
#include <vector>

using namespace std;

int main() {
	vector<shared_ptr <MyClass> > v;
	//Create a bunch of shared pointers
	shared_ptr<MyClass>
		m1(new MyClass), //Object #1
		m2(new MyClass), //Object #2
		m3(new MyClass); //Object #3

	//The vector will add one reference to each added object
	v.push_back(m1);
	v.push_back(m2);
	v.push_back(m3);
	//Every object now has 2 references

	m2.reset(); //Object #2 has 1 reference left
	v.erase(v.begin() + 1); //Object #2 has no reference left

	for (unsigned int i = 0; i <v.size(); ++i) {
		v[i]->method();
	}
	return 0;
}

The size of a shared_ptr<MyClass> is only about 8 bytes. Storing it by copy in a container has very little overhead. The way reference counting works here is very intuitive and exactly as I expected. I threw in a reset() and erase() call to see what will happen. As expected, object #2 gets destroyed after the erase() call above. The output from the program is:

Creating MyClass object
Creating MyClass object
Creating MyClass object
Destroying MyClass object
Called method of MyClass object
Called method of MyClass object
Destroying MyClass object
Destroying MyClass object

Automatic Reference Counting (ARC) Envy in C++

Many old C++ hacks like me who later learned to do programming in Objective-C watched with envy the introduction of ARC. Well, there is no need for that. C++ has shared_ptr that pretty much mimics ARC. Now, I haven’t tested all possibilities. Certainly, I will like to learn more about circular references and what happens when you store a shared_ptr in a vector or map. But, simple cases certainly work like a charm.

Let’s say we have a class called MyClass.

class MyClass {
public:
	MyClass(){
		cout << "Creating MyClass object" << endl;
	}
	virtual ~MyClass(){
		cout << "Destroying MyClass object" << endl;
	}
	void method(){
		cout << "Called method of MyClass object" << endl;
	}
};

Below is how we can manage an object of MyClass using automatic reference counting.

#include <memory>

using namespace std;

shared_ptr<MyClass> returnTest() {
	shared_ptr<MyClass> m(new MyClass);

	m->method();

	return m;
}

int main() {
	shared_ptr<MyClass> m2 = returnTest();

	m2->method();

	return 0;
}

This is a pretty good test. An object is created from a method and returned from there. The return value is assigned to a variable. The output from this program will be:

Creating MyClass object
Called method of MyClass object
Called method of MyClass object
Destroying MyClass object

The behavior is no different from Objective-C. Except that in Objective-C, the returned object will be put on an auto release pool.

On another note, I had to add the –std=c++0x option to GNU++ compiler for shared_ptr to work.

Pausing and Resuming Background Work in Android

The AsyncTask mechanism in Android is very easy to use. It provides a way to cancel work gracefully. Unfortunately, it has no way of pausing and resuming work. This presents a problem when an activity needs to pause work when going in to paused or stopped state.

This morning, I spent a bit of time solving that problem. The result is a ThreadControl class that provides pause, resume and cancel semantics. It can be used from any Java thread, including AsyncTask. Source code for a fully working sample project can be found here in GitHub.

Let’s have a look at a very simple example of an activity that controls background work via the ThreadControl class. It also shows how to code the work done in a background thread.

public class MainActivity extends Activity {
  ThreadControl tControl = new ThreadControl();
  int count = 0;

  public void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.main);

    AsyncTask<Void, Void, Void> task = 
      new AsyncTask<Void, Void, Void>() {
      protected Void doInBackground(Void... params) {
        try {
          //Do some long running work
          while (true) {
            //Pause work if control is paused.
            tControl.waitIfPaused();
            //Stop work if control is cancelled.
            if (tControl.isCancelled()) {
              break;
            }
            ++count;
          }
        } catch (Exception e) {

        }
        return null;
      }
    };
    
    task.execute();
  }

  protected void onDestroy() {
    super.onDestroy();
    //Cancel control
    tControl.cancel();
  }

  protected void onPause() {
    super.onPause();
    
    //No need to pause if we are getting destroyed 
    //and will cancel thread control anyway.
    if (!isFinishing()) {
      //Pause control.
      tControl.pause();
    }
  }

  protected void onResume() {
    super.onResume();
    
    tControl.resume();
  }
}

The cool thing is that you can control as many background threads as you want using the same ThreadControl object. Of course, all threads must call waitIfPaused() for the same ThreadControl object. Also, the ThreadControl class has no dependency on Android. You can use it from any Java application.

AsyncTask and Thread Pooling

In a recent post, I had stated that AsyncTask creates a new thread every time a task is executed. Well, that’s not true. Starting with Android 1.6 Donut, a pool of threads is used. An answer in StackOverflow provides more insight. I have verified most of what is stated there. System can create up to 128 threads. However, only a maximum of 5 threads are kept alive in the pool. Extra threads (beyond 5) are immediately killed after termination of the AsyncTask.

I also found out that calling AsyncTask.cancel(true) has no impact on the pool size. That is, it doesn’t actually kill the thread. Only threads that are killed are the ones beyond the 5 that are kept in the pool.

In summary, because a pool is used, AsyncTask may be used to performs short tasks repeatedly. Unless you are queuing more than 5 tasks at the same time, no new thread will be created. If, however, the number of concurrent tasks exceeds 5, it may be better to use ExecutorService as I said in my post.

That leaves one unanswered question. The relevant section of AsyncTask documentation says:

When first introduced, AsyncTasks were executed serially on a single background thread. Starting with DONUT, this was changed to a pool of threads allowing multiple tasks to operate in parallel. Starting with HONEYCOMB, tasks are executed on a single thread to avoid common application errors caused by parallel execution.

I am puzzled by the last bit about Honeycomb. What does it mean by “tasks are executed on a single thread?” From my tests done in Ice Cream Sandwich, clearly, each task runs in its own separate thread. If you have any idea about what the documentation is saying, please leave a comment here.

Testing with Mock Location Data in Android

The DDMS tool can be used to push out test location during testing. However, it has two serious limitations:

1. DDMS sets location for GPS location provider only. If your application uses network provider then you are out of luck.
2. DDMS can set location for an emulator device only. You can not do testing using a real device.

If you need to test with real device or using the network location provider, you will need to develop a mock provider within the application. A mock provider can represent any location provider – network or GPS. Writing a mock provider itself is easy. Just be careful about removing the feature before publishing your application.

In this article, we will see how to create a mock location provider.

First, we will develop a class that will encapsulate the details:

public class MockLocationProvider {
  String providerName;
  Context ctx;

  public MockLocationProvider(String name, Context ctx) {
    this.providerName = name;
    this.ctx = ctx;

    LocationManager lm = (LocationManager) ctx.getSystemService(
      Context.LOCATION_SERVICE);
    lm.addTestProvider(providerName, false, false, false, false, false, 
      true, true, 0, 5);
    lm.setTestProviderEnabled(providerName, true);
  }

  public void pushLocation(double lat, double lon) {
    LocationManager lm = (LocationManager) ctx.getSystemService(
      Context.LOCATION_SERVICE);

    Location mockLocation = new Location(providerName);
    mockLocation.setLatitude(lat);
    mockLocation.setLongitude(lon); 
    mockLocation.setAltitude(0); 
    mockLocation.setTime(System.currentTimeMillis()); 
    lm.setTestProviderLocation(providerName, mockLocation);
  }

  public void shutdown() {
    LocationManager lm = (LocationManager) ctx.getSystemService(
      Context.LOCATION_SERVICE);
    lm.removeTestProvider(providerName);
  }
}

A brief description of the MockLocationProvider class may be helpful:

• The constructor takes the name of the location provider that this mock provider will replace. For example, LocationManager.GPS_PROVIDER. The calls to the addTestProvider() and setTestProviderEnabled() tells the LocationManager that the given provider will be replaced by mock data.
• The pushLocation() method supplies mock location data for a given provider.

Any activity or service can easily use the class. Here, we are replacing the network provider with a mock one.

public class MainActivity extends Activity {
  MockLocationProvider mock;
  public void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_main);

    mock = new MockLocationProvider(LocationManager.NETWORK_PROVIDER, this);

    //Set test location
    mock.pushLocation(-12.34, 23.45);

    LocationManager locMgr = (LocationManager) 
       getSystemService(LOCATION_SERVICE);
    LocationListener lis = new LocationListener() {
      public void onLocationChanged(Location location) {
          //You will get the mock location
      }
	  //...
    };

    locMgr.requestLocationUpdates(
      LocationManager.NETWORK_PROVIDER, 1000, 1, lis);
  }

  protected void onDestroy() {
   mock.shutdown();
   super.onDestroy();
  }
}

Setting up Security

For mock location to work, certain permissions have to be set.

You will need to request the android.permission.ACCESS_MOCK_LOCATION permission, in addition to any other permission.

<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/>
<uses-permission android:name="android.permission.ACCESS_MOCK_LOCATION"/>

Finally, you will need to enable mock locations for the device using Settings > Developer options > Allow mock locations.

Disabling Mock Location

It is important that you hide the mock location provider business from the release build. A good way to do that is to enable mock location only if the application is being run in debug mode. In your code, check if debuggable flag is set:

if ((getApplication().getApplicationInfo().flags & 
    ApplicationInfo.FLAG_DEBUGGABLE) != 0) {
    mock = new MockLocationProvider(
        LocationManager.NETWORK_PROVIDER, this);

    //Set test location
    mock.pushLocation(-12.34, 23.45);
}

When you test the app using USB debugging or using the emulator, the debug flag is set automatically.

Testing onSaveInstanceState()

Under severe resource shortage scenario, Android can terminate a background activity and even its process. Android makes sure that onSaveInstanceState(Bundle bundle) is called before the activity is killed. The activity can save any uncommitted application state data in the bundle. If user attempts to navigate back to the killed activity, Android will create a new instance and call onCreate(Bundle bundle). The supplied bundle will contain any previously saved state. Alternatively, Android also calls onRestoreInstanceState(Bundle bundle). The activity should attempt to recreate the state from the bundle. If all goes well, user will have no idea that the activity was killed.

Fortunately, most UIView widgets automatically save and restore their states. You need to deal with any other custom state information, for example, current position of a photo in a slide show application.

Keep in mind that invocation of onSaveInstanceState() does not mean that the activity is about to be killed. Android can decide to call it any time after an activity has been paused. Only if the activity was truly killed that onCreate() will receive a non-null bundle and onRestoreInstanceState(Bundle bundle) is called.

Testing state restoration from onCreate() or onRestoreInstanceState() can be tricky. How do you make sure that your activity is killed while in the background? Fortunately, the Dev Tools application that comes with every emulator image comes handy.

Launch Dev Tools. The click Development Settings.

Check Immediately destroy activities.

Now, as soon as an activity goes into background (stopped state), Android will kill it. When you bring the activity to foreground, a new instance will be created and onCreate() will receive a non-null bundle.

The Dev Tools application has special permissions not available to third party applications. This makes it difficult to install in an actual device. Technically it can done by installing a custom ROM but will be a lot of work.

Browsing Android Logs

Is it me or the LogCat browser in Eclipse is broken lately. If I create a filter for a tag and monitor it, the browser stops updating the display. I found the old fashioned way of using adb to browse much better.

Just open a command prompt and go to Android SDK’s platform-tools folder. Then run:

adb logcat

Applying a filter is easy. Let’s say, that the tag name used in logging calls is “MyApp” and you wish to view logs up to verbose level. Then run this command:

adb shell setprop log.tag.MyApp VERBOSE