Based on my experience with Spring, I thought of writing a series of tutorials on different methods of validating form input when working with Spring MVC.

This is the first part of that series, and I will be focusing on basic form data (i.e. data submitted by the user) validation in Spring MVC 3 using declarative annotations. In the future, I am hoping to touch on more advanced topics such as:

1. Displaying custom messages for validation errors
2. Writing custom annotations to validate view models (or fields)
3. Using JSR 303 groups to perform conditional validations
4. Validation using Spring’s Validator interface
5. Comparison of different validation methods in Spring MVC (pros, cons and when to use them)

Hopefully by the end of the series, you will have a good idea about Spring validation mechanisms, and be able to pick the best option(s) for a particular problem.

Continue on to learn how to perform basic annotation-based validations in your Spring MVC 3.x web applications.

Pre-requisits

Before proceeding ahead, I assume that you have some basic understanding about Spring MVC. Also, I would recommend installing Maven to build your projects if you fetch the sample code from GitHub.

Problem Description

Take a simple scenario where we are entering personal information in a web site, as shown in Figure 1. We want to ensure that we only accept the data if all of the following conditions are satisfied; otherwise we present the data back to the user with some helpful information to rectify the issues.

Figure 1: Form to enter personal information

• All fields are mandatory except for ‘comments’.
• Age must be greater than (or equal to) 10
• Date of birth must be entered as ‘yyyy-MM-dd‘ format (e.g. 2000-10-22) and must be in the past (i.e. can’t enter a date in future)
• Comments can be at most 40 characters.

Step-by-step guide to implementing annotation-based validation in Spring MVC

1. Enable annotations

   Declarative validations are specified as annotations (e.g. on field, method or class level). Therefore, we need to enable annotations in Spring in order for Spring MVC framework to pickup our declarative validations and apply them automatically when a form is submitted.

   We do this by adding the tag inside our servlet context xml file (typically under WEB-INF\spring\appServlet folder)

   <!-- inside servlet-context.xml -->
   <mvc:annotation-driven />
   
   <!-- rest omitted for brevity -->

2. Additional Project Dependencies

   We are relying mainly on JSR 303 javax.validation API to add declarative validation support to our Beans. In addition, I also tend to use the hibernate validator APIs that provide more enhanced constraints. If you are using Maven, you will need to add the following dependencies to your project:

   • validation-api jar
   • hibernate-validator jar

   Your pom.xml would contain the following dependencies (when using Maven):

   <dependency>
     <groupId>javax.validation</groupId>
     <artifactId>validation-api</artifactId>
     <version>1.0.0.GA</version>
   </dependency>
   <dependency>
     <groupId>org.hibernate</groupId>
     <artifactId>hibernate-validator</artifactId>
     <version>4.1.0.Final</version>
   </dependency>

3. Add validation rules to the Bean

   Before progressing further, let us have a look at our Bean object that handles the form submission:

   /**
    *
    * Simple form bean without any validations
    */
   public class SimpleFormBean {
   
       private String firstName;
       private String lastName;
       private int age;
       private Date dateOfBirth;
       private String comments;
   
       // getters and setters omitted for brevity
   }

   This is just a plain old Java Object/Bean (POJO). Let us now define the constraints we described earlier using annotations from javax.validation, hibernate.validator and springframework.format.annotation packages.

   import javax.validation.constraints.Min;
   import javax.validation.constraints.Past;
   
   import org.hibernate.validator.constraints.Length;
   import org.hibernate.validator.constraints.NotBlank;
   import org.hibernate.validator.constraints.NotEmpty;
   import org.springframework.format.annotation.DateTimeFormat;
   import org.springframework.format.annotation.DateTimeFormat.ISO;
   
   /**
    * Simple form bean with declarative validation rules
    * (using JSR 303 annotations)
    */
   public class SimpleFormBean {
   
       // must be at least of length 1
       @NotEmpty
       private String firstName;
       // is not blank (i.e. doesn't accept "   ")
       @NotBlank
       private String lastName;
       // defines the minimum age to be 10
       @Min(10)
       private int age;
       // ISO.DATE format is defined as 'yyyy-MM-dd'
       // e.g. 2012-02-16
       @DateTimeFormat(iso = ISO.DATE)
       @Past
       private Date dateOfBirth;
       // at most 40 characters. Accepts null/empty
       @Length(max = 40)
       private String comments;
   
       // getters and setters omitted for brevity

   Have a look at the Javax Validation API and Hibernate Validator documentation for more details on what other annotations are available.

4. @Valid annotation on the request handler

   Next, we need to update our Controller, so that Spring framework will automatically perform Bean validation when the form is submitted. This happens before it reaches our Controller‘s handler method, which allows us to do special things if there are any validation errors (such as redirecting to a generic error page, or resetting form fields etc.).

   The code for the Controller shows the method that processes form submission.

   @Controller
   public class SimpleFormValidationController {
   
       @RequestMapping(value = "/simpleValidationExample", method = RequestMethod.POST)
       public ModelAndView processFormSubmissionWithValidation(@Valid SimpleFormBean formBean, 
                   BindingResult result) {
           ModelAndView mv = new ModelAndView(ViewNameConstants.VIEW_SIMPLE_FORM_VALIDATION);
           
           if (result.hasErrors()) {
               mv.addObject("message", "Some message you add on error");
               mv.addObject("errors", result.getAllErrors());
               return mv;
           }
   
           // Do any other normal processing you might do when the user input is valid
           mv.addObject("message", "Some message you add if everything is ok");
           return mv;
       }
   }

   There are a couple of important things happening in the above code snippet:

   1. Line #5: Mark the Bean representing the form data (SimpleFormBean) with @Valid annotation. Spring framework will pick up this annotation as part of its request handling pipeline, and apply all the JSR 303 annotations on that object to validate the bean. We, as developers, do not have to worry about anything other than specifying the validation rules via annotations!
   2. Line #9: The org.springframework.validation.BindingResult object contains the results of Spring validation. In this particular case, I am checking to see if there are any validation errors, so I can add some special message to be displayed when the page is refreshed. See the Spring API for more details.

   
   
   If you feel adventurous, write a handler similar to above, but without the @Valid annotation. You will see that your Bean is no longer validated by Spring despite your Bean having all the annotations!

5. Re-displaying form with error messages

   It is all good to validate your Bean, but it would be better if you can tell the user what he/she did wrong so their mistakes can be corrected.

   

   Figure 2: After submitting the form with errors

   Figure 2 shows the errors you get when the user enters incorrect information. Note that it doesn’t complain about ‘Comments’ field because it can accept null/empty values.

   We can use the form:errors tag to display field-specific validation errors to the user. For example, the snippet below displays the error if the user submits an empty ‘firstName’ field.

   <form:errors path="firstName" cssClass="error" />

   The full code snippet for generating the form is shown below:

   <%@ taglib uri="http://java.sun.com/jsp/jstl/core" prefix="c" %>
   <%@ taglib uri="http://www.springframework.org/tags/form" prefix="form" %>
   
   ...
   
   <form:form id="form" method="post" modelAttribute="simpleFormBean">
   	<div id="formContent">
   		<div class="header">
   	  		<h2>Form</h2>
   	  		<c:if test="${not empty message}">
   				<div id="message" class="success">${message}</div>	
   	  		</c:if>
   	  		<s:bind path="*">
   			<c:if test="${status.error}">
   		  		<div id="message" class="error">Form has errors</div>
   			</c:if>
   	  		</s:bind>
   		</div>
   		<fieldset>
   	  		<legend>Personal Info</legend>
   	  		<form:label path="firstName">First Name <form:errors path="firstName" cssClass="error" /></form:label>
   	  		<form:input path="firstName" />
   		  		
   	  		<form:label path="lastName">Last Name <form:errors path="lastName" cssClass="error" /></form:label>
   	  		<form:input path="lastName" />
   	  		<form:label path="age">Age <form:errors path="age" cssClass="error" /></form:label>
   	  		<form:input path="age" />
   	  		<form:label path="dateOfBirth">
   				Date of Birth (in form yyyy-mm-dd) <form:errors path="dateOfBirth" cssClass="error" />
   	 		</form:label>
   	  		<form:input path="dateOfBirth" />
   	
   			<form:label path="comments">Comments (40 letters max) <form:errors path="comments" cssClass="error" /></form:label>
   	  		<form:input path="comments" />
   	  	</fieldset>
   	  	<p><button type="submit">Submit (with validations)</button></p>
   	 </div>
   </form:form>

   Things of interest about the above html snippet include:

   1. Use of Spring form taglib to construct the form, labels and input fields. This enables Spring to bind our Bean object to the form data.
   2. Use of form:errors attribute to display errors, if there are any. This is a special attribute that is part of the Spring tag library that displays validation errors based on the field that is wrong.

6. Customising validation error messages

   The messages that you see in red – in Figure 2 above – are default error messages generated by the validators we used. As you can see some of the validator error messages are straightforward, but others are way too verbose to be displayed to an end-user (e.g. error message for date validation above).

   The final part is to customise the error messages displayed. There are a couple of ways in which you can modify the validation messages.

   1. Specifying the custom message when you define the constraint – This is the simplest, and possibly the least elegant of solutions. The code snippet below show us customising the error message when the user doesn’t enter any value for the ‘First name’ field.
      

      public class SimpleFormBean {
      
          @NotEmpty(message = "Hi, first name cannot be empty. Please enter something here :)")
          private String firstName;
      
          // ... omitted for brevity
      }

      Now, instead of “may not be empty” (as shown in Figure 2 above), you will see “Hi, first name cannot be empty. Please enter something here :)” as the error message.

      The reason why I said this approach is not elegant is that you cannot display locale specific messages easily with this approach. This where the 2nd solution for this problem comes in handy!

   2. Use a properties file to manage messages and customise the message key – In short, we define our messages in a .properties file (e.g. webapps\resources\messages.properties) as key-value pairs. Instead of the actual message, we define the key as part of the message attribute for the annotation. The code below illustrates how we can display the same custom message as above using this approach:

      ## messages.properties file
      NotEmpty.SimpleFormBean.FirstNameField = Hi, first name cannot be empty. Please enter something here :)

      And our Bean would look like:

      public class SimpleFormBean {
      
          @NotEmpty(message = "NotEmpty.SimpleFormBean.FirstNameField")
          private String firstName;
      
          // ... omitted for brevity
      }

      We need to do bit more configuration to Spring in order to allow Spring to find these messages. Rather than deviating from the main topic, I will write another article soon describing how to achieve this.

Conclusions

In this tutorial I’ve covered the following aspects related to validating form attributes/data (also known as form backing objects) using JSR 303 compliant declarative annotations in Spring MVC.

1. Enabling annotations in Spring MVC
2. Using @Valid to enable Spring validation on form objects
3. Defining validations on Beans using JSR 303 compliant annotations
4. Writing jsp/html to display validation errors on screen
5. Customising default validation messages

Hope you found the article informative, and let me know if you want me to clarify anything.

A fully working sample project can be found at GitHub if you are interested in playing around.

Thanks!

References

• Source code for GitHub project at :
• Spring Validation Documentation – for more in-depth details about Spring validation.

Thiranjith Weerasinghe

In this article I will be covering the following scenarios with examples:

1. Logging to Console
2. Logging to a File
3. Logging to multiple Appenders (or log files)
4. Restricting logging levels by package name
5. Having multiple appenders with different log levels
6. Logging the output of a specific class or a package to a specific Appender

Logging to Console

The example below will send all log messages with a level of INFO or higher to the console (e.g. DOS prompt). The ConversionPattern determines how the output will be displayed on-screen.

#
## Create a single appender called 'stdout' with 
## a log level of 'INFO'
log4j.rootLogger=INFO, stdout

## Log to console
log4j.appender.stdout=org.apache.log4j.ConsoleAppender
log4j.appender.stdout.layout=org.apache.log4j.PatternLayout
log4j.appender.stdout.layout.ConversionPattern=%-5p: %c - %m%n

Logging to a File

There are various different File appenders that come out of the box with log4j library. These include FileAppender (for continuously appending to a single file), and more advanced file-appenders such as RollingFileAppender that automatically start a new file after reaching a pre-specified size.

See the API for File Appender for more information about possible configuration options.

#
## Create a single appender called 'R' with 
## a log level of 'INFO'. This will create new
## files whenever the current file reaches 100KB
log4j.rootLogger=INFO, stdout

log4j.appender.R=org.apache.log4j.RollingFileAppender
log4j.appender.R.File=rolling-log.log
log4j.appender.R.MaxFileSize=100KB
log4j.appender.R.layout=org.apache.log4j.PatternLayout
log4j.appender.R.layout.ConversionPattern=%-5p: %c - %m%n

Logging to multiple Appenders (or log files)

The example below illustrates how we can have multiple appenders simultaneously. In the example below, all logs with a level INFO or higher will be logged to both the console and a file (file-log.log).

log4j.rootLogger=INFO, stdout, F

# Console appender configuration
log4j.appender.stdout=org.apache.log4j.ConsoleAppender
log4j.appender.stdout.layout=org.apache.log4j.PatternLayout
log4j.appender.stdout.layout.ConversionPattern=%-5p: %c - %m%n

# File appender configuration
log4j.appender.F=org.apache.log4j.FileAppender
log4j.appender.F.File=file-log.log
log4j.appender.F.layout=org.apache.log4j.PatternLayout
log4j.appender.F.layout.ConversionPattern=%-5p: %c - %m%n

Restricting logging levels by package name

Oftentimes you have 3rd party libraries that do their own logging, which can quickly fill up your log. In such cases, you want to restrict logging for some (or all) of those libraries so your logs only show what really matters. Log4j provides a mechanism to do this by restricting log levels on a per-package level. This allows us to specify the logging level on the specified package (including the sub-packages within it).

In the following example, the packages org.springframework.core and org.springframework.web will only log ERROR messages, while the rest of the application will log DEBUG or higher messages. For example, only ERROR logs by org.springframework.web.servlet.mvc.AbstractController class will be logged by our application.

log4j.rootLogger=DEBUG, stdout

# Console appender configuration
log4j.appender.stdout=org.apache.log4j.ConsoleAppender
log4j.appender.stdout.layout=org.apache.log4j.PatternLayout
log4j.appender.stdout.layout.ConversionPattern=%-5p: %c - %m%n

# Restrict logging for some of the Spring MVC libraries
log4j.logger.org.springframework.core=WARN
log4j.logger.org.springframework.web=WARN

How to configure multiple appenders with different log levels

Imagine you want to log INFO and ERROR logs to different files; for example, have file-info.log with all messages of level INFO or higher, and file-error.log to have only ERROR messages.

The log4j.properties file below shows how to accomplish the above task by outputting different levels of logging to different files using the log4j.appender.FError.Threshold attribute.

#
# Initilise the two appenders
# FInfo - Log INFO messages and above
# FError - Log ERROR messages and above
log4j.rootLogger=INFO, FInfo, FError

# FInfo appender will log at default log level (INFO)
log4j.appender.FInfo=org.apache.log4j.FileAppender
log4j.appender.FInfo.File=file-log.log
log4j.appender.FInfo.layout=org.apache.log4j.PatternLayout
log4j.appender.FInfo.layout.ConversionPattern=%-5p: %c - %m%n

# FError appender will log ERROR and above
log4j.appender.FError=org.apache.log4j.FileAppender
# "log4j.appender.FError.Threshold" allows us to customise
# the log level for a specific appender
log4j.appender.FError.Threshold=ERROR
log4j.appender.FError.File=file-log.log
log4j.appender.FError.layout=org.apache.log4j.PatternLayout
log4j.appender.FError.layout.ConversionPattern=%-5p: %c - %m%n

Logging the output of a specific class to a specific Appender

The example below shows how to output the logs from a specific class (PerformanceProfiler class in com.thira.example package) to a dedicated logger/appender.

log4j.rootLogger=DEBUG, stdout

# Console appender configuration
log4j.appender.stdout=org.apache.log4j.ConsoleAppender
log4j.appender.stdout.layout=org.apache.log4j.PatternLayout
log4j.appender.stdout.layout.ConversionPattern=%-5p: %c - %m%n

# Define another appender for the specified class
log4j.logger.com.thira.example.PerformanceProfiler=INFO, Performance
log4j.additivity.com.thira.example.PerformanceProfiler=false
log4j.appender.Performance=org.apache.log4j.RollingFileAppender
log4j.appender.Performance.File=client-portal-performance.log
log4j.appender.Performance.MaxFileSize=2MB
log4j.appender.Performance.MaxBackupIndex=10
log4j.appender.Performance.layout=org.apache.log4j.PatternLayout
log4j.appender.Performance.layout.ConversionPattern=%-5p: %c - %m%n

The highlighted line #9 (log4j.logger.com.thira.example.PerformanceProfiler=INFO, Performance) tells log4j to redirect all to redirect all INFO (or higher) log messages to the appender called ‘Performance‘.

The additivity option in the next line (i.e. line #10) ensures that the INFO (or higher) log messages from com.thira.example.PerformanceProfiler class will not show up on the rootLogger (i.e. stdout appender in the above example). Note that by default, additivity for all appenders are set to true, implying the log messages will appear on all loggers.

References and Resources

Checkout the following resources if you want to find more about log4j:

• Log4j Overview
• API for Log4j Pattern Layout (to learn more about how to change the output of your log file)

Thiranjith Weerasinghe

I kept getting the following error when attempting to run mvn install goal to set up the project:

C:Dev\MavenTest> mvn clean install


[ERROR] Plugin org.apache.maven.plugins:maven-clean-plugin:2.4.1 or one of its dependencies could not be resolved: Failed to read artifa
escriptor for org.apache.maven.plugins:maven-clean-plugin:jar:2.4.1: Could not transfer artifact org.apache.maven.plugins:maven-clean-pl
:pom:2.4.1 from/to central (http://repo.maven.apache.org/maven2): Not authorized by proxy, ReasonPhrase:Proxy Authentication Required (
ISA Server requires authorization to fulfill the request. Access to the Web Proxy filter is denied.  ). -> [Help 1]

...

After few hours of Googling and trial and error, I finally found two methods of getting Maven to work with NTLM proxies.

Step #1: Add proxy settings to your Maven configuration file

1. Open the Maven configuration file at %M2_HOME%/conf/settings.xml. For Linux, this is typically found at
   

   ${user.home}/.m2/settings.xml)

   
   For Windows, this can be found in one of the following locations:
   

   # In Win XP, Vista
   C:\Documents and Settings\username\.m2\settings.xml
   
   # In Windows 7/8
   C:\users\username\.m2\settings.xml

2. Find the section within settings.xml file that defines the proxies node. This should look something like:

   <proxies>
       <!-- proxy
        | Specification for one proxy, to be used in connecting to the network.
        |
       <proxy>
         <id>optional</id>
         <active>true</active>
         <protocol>http</protocol>
         ...
       </proxy>
       -->
   </proxies>

3. Comment out the proxy node and enter your proxy information. Afterwords, the proxies node should look similar to:
   

   <proxies>
       <proxy>
         <!-- id field is optional -->
         <id>something-descriptive-to-identify-your-proxy</id>
         <!-- Tells Maven to use this proxy. Specify 
              'false' if you want to turn it off. -->
         <active>true</active>
         <protocol>http</protocol>
         <!-- ENTER YOUR PROXY HOST NAME -->
         <host>company.proxy.host.com</host>
         <!-- ENTER YOUR PROXY HOST'S PORT NUMBER -->
         <port>8080</port>
         <!-- ENTER YOUR USER NAME TO LOGIN TO THE HOST -->
         <username>myUserName</username>
         <!-- ENTER YOUR PASSWORD ASSOCIATED WITH THE USERNAME -->
         <password>myPassword</password>
         <!-- Any URLs that you want to filter out 
             (e.g. local repository?). 
              Otherwise just keep this as it is -->
         <nonProxyHosts>local.net|some.host.com</nonProxyHosts>
       </proxy>
     </proxies>

   
   IMPORTANT: Ensure that you change the host, port, username and password fields to match your environment/proxy setup.

   If the above settings doesn’t work, then you might want to change the username field to include the domain that the user belongs to. e.g.

   <username>myDomain\myUserName</username>

Step #2: Add wagon-http-lightweight extension

Wagon HTTP lightweight library allows us to overcome authentication limitations in Maven (3.0.4) when working with NTLM proxies. We can follow the steps below to add the Wagon HTTP lightweight library as a Maven extension:

1. Download the wagon-http-lightweight-2.2.jar from http://repo.maven.apache.org/maven2/org/apache/maven/wagon/wagon-http-lightweight/2.2/wagon-http-lightweight-2.2.jar
2. Copy the wagon-http-lightweight-2.2.jar to %M2_HOME%/lib/ext folder.

Example POM.xml to test the solution

To test our approach, first create a simple Maven project with the following pom.xml:

<!-- pom.xml -->
<project xmlns="http://maven.apache.org/POM/4.0.0" 
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <groupId>com.thira.testmavenplugindl</groupId>
  <artifactId>test-maven-plugin-dl</artifactId>
  <version>0.0.1-SNAPSHOT</version>
  <name>Test Maven Plugin Download Issue</name>
  <description>Example pom file to test Maven dependency download with NTLM proxies</description>
</project>

mvn clean install

Check your local repository directory (as defined in settings.xml file) to ensure all the dependencies are correctly downloaded.

Thiranjith Weerasinghe

A while back, I wrote a tutorial on how to dynamically monitor network connectivity in Android. However, sometimes all you want is to check if your phone has an active network connection at any given time (i.e. not to constantly monitor its status).

The simplest way to check network connectivity at any given point in time is to:

1. Create a utility function to check network status as shown below
   

   public static boolean isOnline(Context context) {
           ConnectivityManager cm = (ConnectivityManager)context.getSystemService(Context.CONNECTIVITY_SERVICE);
           NetworkInfo activeNetwork = cm.getActiveNetworkInfo();
           
           return activeNetwork != null && activeNetwork.isConnectedOrConnecting();
   }

2. Add the following permission to the Android Manifest in order to monitor current network state

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

Explaining the utility function

There are several key discussion points above the isOnline(Context) utility function I described earlier:

• ConnectivityManager#getActiveNetworkInfo() method can return null if the phone is either in Airplane mode or all network interfaces are turned off manually. Therefore, we need to do the null check (activeNetwork != null) before invoking isConnectedOrConnecting() method.
• isConnectedOrConnecting() method checks for networks that are in the process of being connected. Depending on the requirements, you might want to use a more strict version where the method returns true only if the network is already connected. This can be achieved by replacing isConnectedOrConnecting() method with isConnected(). See the Android SDK for more details about the method.

Thiranjith Weerasinghe

Despite rising popularity of RESTful services, there are still a significant number of SOAP-based web services around that are being consumed by mobile applications; specially when working in the enterprise world. Android does not have native support for web service consumption, and this handy light-weight library called kSOAP2 allows Android applications to easily and efficiently consume SOAP-based web services.

In this tutorial I will show you how to use kSOAP2 in Android to consume a publicly available SOAP-based web service. A fully working example of an Android project illustrating the use of kSOAP2 can be found at GitHub.

Introducing the service and operations

I am using a publicly available web service from www.service-repository.com that allows us to view weather information. I will be focusing on two specific operations to highlight the basic features of using kSOAP2:

1. GetWeatherInformation: A zero-argument operation that return weather information managed by the service (You can have a look at the request and response XML from here)
2. GetCityForecastByZIP: A single argument operation that returns weather forecast for a city (argument specifies the US Zip code). You can have a look at the request and response XML from here

The service definition can be downloaded/viewed from this link (open it in Notepad or any other text-editor to view the content).

Creating a new Android project with kSOAP2

1. Create a standard Android project
2. Download the ksoap2-android-assembly-jar-with-dependencies.jar from kSOAP2 home page
3. Copy the downloaded jar file to your Android project’s libs folder. This will enable your Android application to automatically pick up this library when it generates the final artefacts (i.e. the APK file)
4. Add the android.permission.INTERNET permission to your application’s Manifest.xml file to allow your application to talk to web services. Add the following code snippet to your application’s MANIFEST:
   

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

NOTE: There are multiple ways in which you can include kSOAP2 in your Android project, and the method I described above is the most simplest. You can read about other options (e.g. in Maven builds or as an Android library etc.) at here.

Invoking a web service request

Invoking a web service with kSOAP2 involves the following steps:

1. Create a SOAP Envelope using the org.ksoap2.serialization.SoapSerializationEnvelope class.
2. Set the request information for the SOAP Envelope. The request information will be represented by a org.ksoap2.serialization.SoapObject object. I will show how to create request objects shortly in the next section.
3. Create an HTTP Transport request object to deliver the SOAP request (org.ksoap2.transport.HttpTransportSE)
4. Send the SOAP request over HTTP using the HTTP Transport and SOAP Envelope objects created earlier. This call is a synchronous call.
5. Process the web service response (or handle any unexpected errors). A detailed example of processing a relatively complex web service response can be found later in the article.

The code snippet below summarises the above steps in Android:

SoapObject parameter = getSOAPRequestParameter();
// 1. Create SOAP Envelope 
SoapSerializationEnvelope envelope = new SoapSerializationEnvelope(SoapEnvelope.VER11);
// 2. Set the request parameters
envelope.setOutputSoapObject(parameter);

// 3. Create an HTTP Transport object to send the web service request
HttpTransportSE httpTransport = new HttpTransportSE(WSDL_URL);
httpTransport.debug = true; // allows capture of raw request/respose in Logcat

// 4. Make the web service invocation
httpTransport.call(WS_NAMESPACE + WS_METHOD_NAME, envelope);

// Logging the raw request and response (for debugging purposes)
Log.d(TAG, "HTTP REQUEST:\n" + httpTransport.requestDump);
Log.d(TAG, "HTTP RESPONSE:\n" + httpTransport.responseDump);

// 5. Process the web service response
if (envelope.bodyIn instanceof SoapObject) { // SoapObject = SUCCESS
    SoapObject soapObject = (SoapObject) envelope.bodyIn;
    T processedResponse = parseSOAPResponse(soapObject);
    // ... do whatever you want with this object now
} else if (envelope.bodyIn instanceof SoapFault) { // SoapFault = FAILURE
    SoapFault soapFault = (SoapFault) envelope.bodyIn;
    throw new Exception(soapFault.getMessage());
}

As mentioned above, your SOAP requests are synchronous and depending on network conditions it can take a while before even a simplest of requests can be invoked. This can cause application freezes and crashes. Therefore, it is highly recommended to do both the service invocation and request processing within a background thread in Android.

This can be achieved using an AsyncTask, and putting the above code inside its doInBackground method. You can have a look at how this is incorporated into the solution in my sample project at Github.

Creating a service request

All SOAP requests are created in kSOAP2 using a org.ksoap2.serialization.SoapObject object. You need to specify the web service namespace, and the service method name when constructing a SoapObject. You can find the namespace and method name details in the wsdl file itself, or in the documentation provided by the service provider.

Example SOAP request with no arguments

For example, you can create a zero-argument SOAP request required for the GetWeatherInformation service method as follows:

// see com.example.ksoap2.wsclient.weather.GetWeatherInformationTask class
// for full source code
SoapObject request = new SoapObject("http://ws.cdyne.com/WeatherWS/" /* namespace */, 
                                    "GetWeatherInformation" /* web service method */);
// set the request in the envelope (shown in the previous section)
envelope.setOutputSoapObject(parameter);

Example SOAP request with an argument

Lets have a look at a slightly more complex scenario that involves passing in arguments to a web service request, such as the case with GetCityForecastByZIP service method. As per its service definition, it accepts a single argument that describe the zip code of a city.

The only step different from the above no-argument scenario, is that now we are adding request properties to our SoapObject using PropertyInfo class. org.ksoap2.serialization.PropertyInfo class enables us to add property name-value pairs as illustrated in the code snippet below.

NOTE: Adding complex request objects is out of scope for this article. I will be writing another article soon about that soon.

String zipCode = 12345; // example zip code
// 1. Create the SoapObject 
SoapObject request = new SoapObject("http://ws.cdyne.com/WeatherWS/" /* namespace */, 
                                    "GetCityForecastByZIP" /* web service method */);
// 2. Define the property
PropertyInfo property = new PropertyInfo();
property.setNamespace("http://ws.cdyne.com/WeatherWS/"); // namespace to ensure that the element-name is prefixed with the namespace
property.setName("ZIP"); // name of the argument as per wsdl document
property.setValue(zipCode); // value of the property

// 3. Add the property to the request object        
request.addProperty(property);

// .. this request will then be passed in to the SoapEnvelope
// e.g. envelope.setOutputSoapObject(parameter);

Processing service response

Now to the final part of the process; deciphering the service response received from the provider.

1. Detecting the validity of the response: Firstly, we have to detect whether our service request succeeded or not. The following code snippet shows how to detect this:

   // after calling the web service using HTTP Transport ..
   
   if (envelope.bodyIn instanceof SoapObject) { // SoapObject = SUCCESS
      SoapObject soapObject = (SoapObject) envelope.bodyIn;
      result = parseSOAPResponse(soapObject);
   } else if (envelope.bodyIn instanceof SoapFault) { // SoapFault = FAILURE
      SoapFault soapFault = (SoapFault) envelope.bodyIn;
      throw new Exception(soapFault.getMessage());
   }
   
   ...
   private CityForecastBO parseSOAPResponse(SoapObject response) {
           CityForecastBO cityForecastResult = null;
           SoapObject cityForecastNode = (SoapObject) response.getProperty("GetCityForecastByZIPResult");
   
           // ... 
           // more code in here to populate the CityForecastBO object from the 
           // response object (illustrated in the steps below)
   
           return cityForecastResult;
   }

2. Parsing the web service response in a success case: The code for parsing depends on web service you invoke (i.e. wsdl specification).
   A snippet of the SOAP response received is shown below (you can test this out by entering the zip code 12345 into the request parameter here:

   <soap:Body>
       <GetCityForecastByZIPResponse xmlns="http://ws.cdyne.com/WeatherWS/">
         <GetCityForecastByZIPResult>
           <Success>true</Success>
           <ResponseText>City Found</ResponseText>
           <State>NY</State>
           <City>Schenectady</City>
           <WeatherStationCity>Albany</WeatherStationCity>
           <ForecastResult>
             <Forecast>
               <Date>2012-10-16T00:00:00</Date>
               <WeatherID>2</WeatherID>
               <Desciption>Partly Cloudy</Desciption>
               <Temperatures>
                 <MorningLow>45</MorningLow>
                 <DaytimeHigh>55</DaytimeHigh>
               </Temperatures>
               <ProbabilityOfPrecipiation>
                 <Nighttime>30</Nighttime>
                 <Daytime>20</Daytime>
               </ProbabilityOfPrecipiation>
             </Forecast>
           </ForecastResult>
         </GetCityForecastByZIPResult>
       </GetCityForecastByZIPResponse>
     </soap:Body>

   The following code snippets demonstrate how we can use kSOAP library to parse the response xml.

3. Reading simple (top-level) parameters:

   SoapObject cityForecastNode = (SoapObject) response.getProperty("GetCityForecastByZIPResult");
   // see the wsdl for the definition of "ForecastReturn" (which can be null/empty)
   // i.e. <s:element name="GetCityForecastByZIPResponse"> element 
   if (cityForecastNode != null) {
       // see <s:complexType name="ForecastReturn"> element for definition of "ForecastReturn"
              
       // "Success" is a mandatory node, so no need to do any null checks.
       boolean isSuccess = Boolean.parseBoolean(cityForecastNode.getPrimitivePropertySafelyAsString("Success"));
                       
       String responseText =  cityForecastNode.getPrimitivePropertySafelyAsString("ResponseText");
       String state =  cityForecastNode.getPrimitivePropertySafelyAsString("State");
       String city =  cityForecastNode.getPrimitivePropertySafelyAsString("City");
       String weatherStationCity =  cityForecastNode.getPrimitivePropertySafelyAsString("WeatherStationCity");
   }

   The getPrimitivePropertySafelyAsString(String) method allows us to extract any primitive property of the SoapObject as a String. If the property value is not present (which is the case if the attribute is optional), then we will get a null value back from this method.

4. Reading array objects: If you take a closer look at the XML snippet for the service response, you will see that the ForecastResult node is an array consisting of zero or more Forecast nodes. We can iterate through these array structures using a simple for loop as shown below:

   // "ForecastResult" (an array) can be empty according to the wsdl definition. Therefore, we do a null check before processing
   // any data.
   SoapObject forecastResultsNode = (SoapObject) cityForecastNode.getPropertySafely("ForecastResult");
   if (forecastResultsNode != null) {
       // Definition for Forecast node can be found at <s:complexType name="Forecast"> element in wsdl
       for (int idx = 0; idx < forecastResultsNode.getPropertyCount(); idx++) {
            SoapObject forecastNode = (SoapObject) forecastResultsNode.getProperty(idx);
                       
            String date =  forecastNode.getPrimitivePropertySafelyAsString("Date");
            short weatherId =  Short.parseShort(forecastNode.getPrimitivePropertySafelyAsString("WeatherID"));
       }
   }

   There are few interesting points about the code snippet above:

   1. getPropertyCount() method allows us to get the total number of child nodes within a SoapObject; in this case it happens to be the same as the number of Forecast nodes.
   2. forecastResultsNode.getProperty(idx) allows us to retrieve a child node (i.e. SoapObject) at a given position.
   3. According to the wsdl for the weather service, ForecastResult is an optional node. Therefore, we need to do a null check before parsing the forecastResultsNode object.
5. Reading values from nested nodes: As per wsdl definition, both “Temperatures” and “ProbabilityOfPrecipiation” nodes are nested complex types within a Forecast node. We can extract nested complex types within a SoapObject using the getProperty(String nodeName) method as illustrated below.
   

   // "Temperatures" and "ProbabilityOfPrecipiation" nodes are mandatory within a "Forecast" node
       //      <s:element minOccurs="1" maxOccurs="1" name="Temperatures" type="tns:temp"/>
       //      <s:element minOccurs="1" maxOccurs="1" name="ProbabilityOfPrecipiation" type="tns:POP"/>
       SoapObject temperatureNode = (SoapObject)forecastNode.getProperty("Temperatures");
       String moringLowTemp =  temperatureNode.getPrimitivePropertySafelyAsString("MorningLow");
       String daytimeHighTemp =  temperatureNode.getPrimitivePropertySafelyAsString("DaytimeHigh");
       forecast.setTemperature(moringLowTemp, daytimeHighTemp);
                       
       SoapObject precipicationProbabilityNode = (SoapObject)forecastNode.getProperty("ProbabilityOfPrecipiation");
       String nightTimePercentage =  precipicationProbabilityNode.getPrimitivePropertySafelyAsString("Nighttime");
       String dayTimePercentage =  precipicationProbabilityNode.getPrimitivePropertySafelyAsString("Daytime");
       forecast.setPrecipiationProbability(nightTimePercentage, dayTimePercentage);

Wrap up

In this totorial, I have demonstrated how to:

1. Set up an Android project with kSOAP2 library
2. How to create a SOAP request (with an without parameters) and invoke a web service
3. How to parse the web service response (extracting both simple and complex types)

The full source code for the above code snippets can be found at my GitHub repository. The GetCityForecastByZipCodeTask.java and GetWeatherInformationTask.java classes (in com.example.ksoap2.wsclient.weather package) contains the core logic of using kSOAP2 library to invoke web services.

Please feel free to get in touch with me if you have any questions or suggestions.

Thiranjith Weerasinghe

Bazaarfind is a price comparison site for sports and nutritional supplements. Currently the comparison data is sourced from stores within New Zealand. Give it a go next time you happen to be in the online market to purchase supplements!

We are hard at work to add new features, and I would greatly appreciate if you can take few minutes to checkout the site and give me your feedback :)

If you like what you see, and want to be kept up to date of the site’s progress and latest deals:

1. Like us on Facebook at http://www.facebook.com/BazaarFindNZ, and/or
2. Follow us on Google+

Feel free to share the news with your friends and family!

Thiranjith Weerasinghe

If you are new to rooting, or not 100% sure what it means, I highly recommend to read this article before proceeding ahead.

Disclaimer: Rooting and installing custom ROMs void your phone’s warranty in most scenarios. I am not responsible for any damages that may incur (however unlikely it may be) by following the instructions on this blog post. It is important to keep in mind that rooting your phone does not wipe out your stock ROM (e.g. HTC Sense for HTC devices, TouchWiz for Samsung etc). Bottom line is only attempt to root your phone if you are comfortable with it; otherwise find someone who knows what they are doing rather than potentially bricking your phone :)

Having said that, I successfully managed to root several HTC One X phones by following the steps outlined below.

Rooting the HTC One X

1. Unlocking the Bootloader: Android bootloader can be thought of as a protected area of your phone that controls what you can do with it. First, we need to unlock this portion so we can unlock other parts of the phone (i.e. root your phone). You can read more about bootloaders here.
   
   

   WARNING: Unlocking the bootloader will wipe all the application-data on your phone (e.g. application-specific information stored within the phone, SMS messages etc.). Please back up all your data before proceeding ahead

   1. Download HTC Sync (from here) and ensure you have the latest Java runtime (from http://java.com/) and Android SDK (can be downloaded and installed from ).
   2. Go to HTC Dev Centre and register (you need to enter a valid email address here because HTC will use that to send your unlock code)
   3. Go to http://www.htcdev.com/bootloader/
   4. Select ‘All other supported devices‘ option for Supported Devices, and click ‘Begin Unlock Bootloader‘ button
   5. Follow the steps exactly as instructed (there are about 12 steps and the process won’t take more than 5 minutes)

   Once you are done with all the steps, you will have an Unlocked Bootloader.

2. Installing the ClockwordMod image : Even after unlocking, the default bootloader for HTC lacks features that allows us to root and install custom ROMs. That is where ClockwordMod comes in handy. It is a custom bootloader that allows you to root your phone, install custom ROMs, patch ROMs, backup your phone (similar to ISO images on PCs) and restore your backups.
   1. Download the latest ClockwordMod image from http://download.clockworkmod.com/recoveries/recovery-clockwork-touch-5.8.4.0-endeavoru.img
   2. Please the recovery-clockwork-touch-5.8.4.0-endeavoru.img file in the folder containing fastboot.exe file (from step #1 above in unlocking the bootloader). The remainder of this article will refer to this folder as C:\%HTC_ROOT_FILES%
   3. Ensure your phone is not connected to the PC, and reboot your HTC One X phone (i.e. press on the power button, and then select ‘Reboot’) while holding down the ‘Volume Down’ button. This will take you to the “HBOOT” screen (bunch of options in a white background).
   4. Use the Volume up and down keys to navigate up/down and select ‘FASTBOOT‘ option. Press the phone’s power button to select the option.
   5. Connect your phone to the PC using the USB cable
   6. Open a command prompt at C:\%HTC_ROOT_FILES% folder and type the following and press enter:
      
      fastboot flash recovery recovery-clockwork-touch-5.8.4.0-endeavoru.img
      This will install the ClockworkMod recovery onto your phone.
   7. Reboot the phone, once the above command is successfully completed. You will have to go through setting up the phone/wi-fi at this point, but don’t spend too much time on it if you are planning to install a custom ROM after rooting the phone.
3. Granting super-user permissions (a.k.a. rooting your HTC One-X) : We rare almost done with rooting your phone and at the final step.
   1. Download ClockworkMod compatible SuperUser installer from XDA Developers forum, and save the file on to your phone’s external memory. More information about the superuser app can be found at http://forum.xda-developers.com/showthread.php?t=1538053.
   2. Reboot the phone to the “HBOOT” menu (Power down and restart while holding the volume down key)
   3. Select “Recovery” and press the Power button to make the selection. After few seconds (5-30s) you will go to the ‘ClockworkMod Recovery’ console.
   4. Make a backup of your phone at this point (so we can recover it back if something goes wrong) by going to ‘backup and restore‘ and following the appropriate steps. (use volume up/down to navigate between different items and power button to make the selection)
   5. Once the backup is completed, go back to the ‘ClockworkMod Recovery’ console
   6. Select ‘Install zip from sd card’
   7. Select ‘Choose zip from sdcard’
   8. Now you will be presented with the sdcard content for your phone. Navigate the folders and select the superuser zip file you copied earlier. At this point you will be presented with a confirmation screen. Select ‘YES/Install‘ to proceed ahead. Wait until the process is done (can take few minutes)
   9. Once the superuser app is installed, navigate back to the main clockwordmod console.
   10. You can either create another backup at this point, or simply select ‘reboot system now‘. Rebooting first time could take several minutes (ranging between 2-5 minutes), so be patient.

That is it! Now you have a rooted HTC One X!

Here are few links to get you started on making good use of your newly rooted device. Remember to make a new backup through CWM before installing any new ROM, theme or a mod. You can find an extensive list of themes and mods from here.

Thiranjith Weerasinghe

I thought of answering some basic questions such as what exactly is “Rooting”?, and what benefits do you get by rooting your phone? Hopefully this will clear some misconceptions floating around and give you a clearer picture about what rooting is all about.

What is “rooting”?

Android is a Linux-based operating system, and have different “user classes” that have different privileges that determines what you can do with your phone. As a normal Android user, you have access to install/uninstall applications, work with certain hardware features like compass, camera, phone radio etc. and just work with it in general. However, you are restricted from interacting with the low-level operating system features that require elevated “access” (rights).

Without getting too technical, rooting your Android phone can be thought of as the act of elevating your system privileges so you can do things that your carrier and/or the phone manufacturer doesn’t allow you to do. Essentially, rooting your phone gives you the opportunity to do things that were previously not possible (i.e. restricted) with your Android phone.

It is important to keep in mind that rooting your phone does not wipe out your stock ROM (e.g. HTC Sense for HTC devices, TouchWiz for Samsung etc); you will still get to use the stock ROM you had before rooting the phone. Often you can still get carrier updates after rooting the phone (at least in my experience with Nexus One and Samsung Galaxy S2), but this will vary depending on your phone model.

Why would you “want” to root your Android phone?

The restrictions imposed by carriers and phone manufactures are good enough (or tolerable) for majority of the users to just get on with their normal day-to-day tasks with their smart-phones. Majority of the time these restrictions ensure you can’t crash/brick your phone by accident.

However, there are quite a few functions and features that are severely limited or even blocked, due to the “locking” by the mobile carriers and/or phone manufacturers. I’ve listed a few of those carrier/manufacturer imposed limitations based on the experiences of my friends:

• Inability for customers to move between carriers, or even between different plans (within the same carrier), due to “locked” handsets (specially in USA)
• Inability to change the boot-up animations as these are set to display the carrier logo in most cases.
• Software limitations imposed to boost carrier specific offerings. These include blocked VOIP applications (e.g. Skype, Google Voice etc.) and tethering.

A more in-depth discussion about these limitations can be found here.

The way to get around this is to acquire ‘root’ (i.e. Administrator) access on the device, so you can install/modify/fix/break anything you want.

Benefits of rooting Android phone

Rooting your Android device helps you to get around aforementioned issues, as well as allowing you to do a plethora of other interesting things with your phone, that are otherwise not possible. This is because rooting allows you to install/modify/fix/break anything you want on your phone!

Few of the other things you can do, after rooting your phone includes:

• Ability to install custom ROMs that provides different experience/benefit to your stock ROM. Pros/cons of custom ROMs is a whole different topic and I will save it for another post!
• Ability to install applications that allows you to do things that are not possible on non-rooted devices. These include:
  • Ability to browse the whole folder structure of your phone (as opposed to just the external memory) using apps such asRoot Explorer.
  • Ability to back up and restore your applications (including the local data/state) using apps such as Titanium Backup.
  • Ability to overclock your phone to get some extra oomph out of those low-mid range phones (e.g. SetCPU for Root Users)
  • Synchronize your phone’s clock with NTP servers using apps like ClockSync.
• Ability to get rid of bloat-ware applications that are otherwise impossible to get rid of; specially if you are on a pre-ICS (Android 4+) ROM.
• Connect to your phone via SSH/ADB to recover any data if your phone doesn’t start-up properly

In short, rooting opens up a whole set of possibilities and options while giving you complete control of the system

Drawbacks of rooting your phone

There are two main drawbacks/risks of rooting Android phones:

1. It almost always voids the phone warranty (I’d like to hear about exceptions to this!)
2. Not correctly completing the rooting process can cause anything from just wiping all your data on the phone (messages, contacts etc.) to completely bricking it! So make sure you read the rooting instructions VERY carefully and read reviews before following instructions to root your phone.

Where to from here?

So have you decided to give it a go and root your phone? The first step is to find out how to root your phone. The instructions often vary from one model to another and the best place to check is the xda-developer forums. Go to the thread marked “Android Development” for your phone model. It is an active community and you are sure to find instructions for rooting and installing custom ROMs on popular phone models. Otherwise Google is your friend!

Here are few links to popular Android applications for rooted devices:

• A series of articles presenting top applications for rooted devices
• 10 applications highly recommended for rooted users
• Another list of 10 applications for rooted Android devices by Life Hacker

NOTE: I take no responsibility for any damage caused by rooting your phone. Please do it at your own risk or get someone who knows what they are doing to root your phone!

Thiranjith Weerasinghe

The best thing about this approach is that you don’t lose your existing configuration settings for the WordPress plugins (except for the one that caused issues in the first place).

Here are the detailed steps on how I went about getting my site back up.

1. Disable all the WordPress plugins manually

1. Go to the cPanel of your web-server, and click on phpMyAdmin.
2. Click on the database for your wordpress
3. All the wordpress plugins are specified in the wp_options table’s ‘active_plugins‘ row. We need to remove the entry for the problematic plugin from this row’s ‘option_value’ column, so WordPress will disable all the plugins. Run the following sql statement to obtain the ‘active_plugins’ row.
   

   SELECT option_value FROM  wp_options
         WHERE option_name LIKE '%active_plugins%'

   
   You should get something like below that defines all the active plugins you had.
   

   a:9:{i:0;s:19:"plugin1/plugin1.php";i:1;s:45:"plugin2/plugin1.php";}

4. Update the active_plugins after removing the value for the pulgin that caused issues from the value above. In my case it was plugin1, so the sql to update the row looked as follows:
   

   UPDATE  wp_options 
     SET option_value = 'a:9:{i:1;s:45:"plugin2/plugin1.php";}' 
     WHERE wp_options.option_name = 'active_plugins';

   Note that I removed the part that says “i:0;s:19:”plugin1/plugin1.php”;” from the original result I got.

2. Go to wp-admin section of your WordPress blog

If you followed all the above steps, you should now be able to go back to your WordPress blog and get it to load without any errors. Navigate to the wp-admin page for your blog and login as the WordPress administrator.

3. Re-enable all the plugins

At this point, WordPress would have disabled all your other plugins.

1. Go to Plugins->Installed Plugins section under your Dashboard
2. Activate all the plugins, except for the one that caused problems
3. Load the live site on a different browser/tab to make sure those plugins are workings

4. Fix the problematic plugin

If you want to keep using that plugin, the best way is to just delete the plugin and reinstall it. The downside is you will have to reconfigure the plugin to suit your needs!

Let me know if you have used any other means to solve the same issue!

Thiranjith Weerasinghe

I will be introducing two methods to stop the screen from being dimmed. The two methods provide means of accomplishing this depending on the current state of your application; i.e. whether it has an Activity on the foreground (visible on screen) or running on the background (as a Service).

1. Use of FLAG_KEEP_SCREEN_ON option for your Activity.
2. Use of a WakeLock.

1. Use of FLAG_KEEP_SCREEN_ON option

This is the recommended way to prevent screen timeout for an Android Activity. Doing so would keep your screen turned on as long as your Activity is visible (i.e. on the foreground).

The advantages of this method include:

• Do not need any special permissions to implement the solution
• Gives you greater control by having the screen on only for selected Activities, rather than for the whole application.
• A more power-efficient solution compared to alternate methods.
• Developer does not have to explicitly manage screen visibility, as the behaviour will automatically be reverted back to default once the Activity is no longer visible on screen (e.g. user pressed the back button, or another application was opened on top).

There are two ways that you can achieve this.

1. Using android:keepScreenOn XML attribute on the Activity’s layout (see line #5).

   You don’t have to do anything special in the Activity class. Another benefit of this particular method is that you can control screen timeout on a per View basis as opposed to per-Activity basis.

   <!-- main_layout.xml file -->
   <?xml version="1.0" encoding="utf-8"?>
   <LinearLayout
     xmlns:android = "http://schemas.android.com/apk/res/android"
     android:keepScreenOn = "true"
     android:orientation = "vertical"
     android:layout_width = "fill_parent"
     android:layout_height = "fill_parent">
     <!-- other views ommitted for brievity -->
   </LinearLayout>

   public class MyActivity extends Activity {
   
       public void onCreate(Bundle savedInstanceState) {
   		super.onCreate(savedInstanceState);
   		setContentView(R.layout.main_layout);
   		// ...
       }
   }

2. Using the FLAG_KEEP_SCREEN_ON flag within your Activity

   You set up the flag in your Activity’s onCreate (or onStart depending on the desired effect) method to keep the screen on programatically. This allows you the option to easily switch back to the default screen timeout behaviour by invoking the stopForceScreenOn() method in the example below.

   <!-- main_layout.xml file -->
   <?xml version="1.0" encoding="utf-8"?>
   <LinearLayout
     xmlns:android = "http://schemas.android.com/apk/res/android"
     android:orientation = "vertical"
     android:layout_width = "fill_parent"
     android:layout_height = "fill_parent">
     <!-- other views ommitted for brievity -->
   </LinearLayout>

   public class MyActivity extends Activity {
   
       public void onCreate(Bundle savedInstanceState) {
   		super.onCreate(savedInstanceState);
   		setContentView(R.layout.main_layout);
   
   		getWindow().addFlags(WindowManager.LayoutParams.FLAG_KEEP_SCREEN_ON);
       }
   
       private void stopForceScreenOn() {
   		getWindow().clearFlags(WindowManager.LayoutParams.FLAG_KEEP_SCREEN_ON);
       }
   }

2. Use of a WakeLock.

A WakeLock can be used by your application to turn the screen on (amongst other things), and keep it on until the WakeLock is released. Use of WakeLocks drain your battery life significantly. Therefore WakeLocks are only recommended to be held for short periods of time and must be released as soon as possible.

Moreover, use of a WakeLock is the only way to programatically turn the screen on when the phone is already sleeping (e.g. when responding to a message received over the web etc.).

Using a WakeLock is a 3-step process consisting of the following:

1. Grant the application permission to use WakeLocks by including the following in your manifest
   

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

2. Acquire a WakeLock.

   The code snippet below demonstrate how to obtain a WakeLock that will cause the screen to be lit (but dimmed) until the lock is released.

   PowerManager pm = (PowerManager) getSystemService(Context.POWER_SERVICE);
   	PowerManager.WakeLock wl = pm.newWakeLock(PowerManager.SCREEN_DIM_WAKE_LOCK, "My Tag");
   	wl.acquire();

3. Release the WakeLock once no longer necessary. The screen will continue to stay on until it is released.

   wl.release();

Please refer to the Android SDK documentation if you want to know more about WakeLocks.

Conclusions:

As a rule of thumb, don’t forcefully keep the screen on for long periods unless you have a visible Activity. Having the screen on will use more power regardless of the method you use to accomplish it!

Due to the high power consumption by WakeLocks, I would recommend using them only via background Services to give a cue to the user. You must ensure that the WakeLock is released soon to prevent battery drain.

If you want to keep the screen on when running an Activity, always use the FLAG_KEEP_SCREEN_ON flag (either in your Activity or in XML layout).

As always, please let me know if you have any questions and your feedback is always appreciated!

Thanks!

Thiranjith Weerasinghe