The Preferences API was first covered here shortly after it was introduced with the 1.4 version of the standard platform: the July 15, 2003 article, the Preferences API.

That article described how to get and set user specific preferences. There is more to the Preferences API than just getting and setting user specific settings. There are system preferences, import and export preferences, and event notifications associated with preferences. There is even a way to provide your own custom location for storage of preferences. The first three options mentioned will be described here. Creating a custom preferences factory will be left to a later tip.

System Preferences

The Preferences API provides for two separate sets of preferences. The first set is for the individual user, allows multiple users on the same machine to have different settings defined. These are called user preferences. Each user who shares the same machine can have his or her own unique set of values associated with a group of preferences. Something like this could be like a user password or starting directory. You don’t want every person on the same machine to have the same password and home directory. Well, I would hope you don’t want that.

The other form of preferences is the system type. All users of a machine share the same set of system preferences. For instance, the location of an installed printer would typically be a system preference. You wouldn’t necessarily have a different set of printers installed for different users. Everyone running on one machine would know about all printers known by that machine.

Another example of a system preference would be the high score of a game. There should only be one overall high score. That’s what a system preference would be used for. In the previous tip you saw how userNodeForPackge() — and subsequently userRoot() — was used to acquire the user’s preference node, the following example shows how to get the appropriate part of the system preferences tree with systemNodeForPackage() — or systemRoot() for the root. Other than the method call to get the right preference node, the API usage is identical.

The example is a simple game, using the game term loosely here. It picks a random number from 0 to 99. If the number is higher than the previously saved number, it updates the “high score.” The example also shows the current high score. The Preferences API usage is rather simple. The example just gets the saved value with getSavedHighScore() , providing a default of -1 if no high score had been saved yet, and updateHighScore(int value) to store the new high score. The HIGH_SCORE key is a constant shared by the new Preferences API accesses.

  private static int getSavedHighScore() {
    Preferences systemNode = Preferences.systemNodeForPackage(High.class);
    return systemNode.getInt(HIGH_SCORE, -1);
  }

  private static void updateHighScore(int value) {
    Preferences systemNode = Preferences.systemNodeForPackage(High.class);
    systemNode.putInt(HIGH_SCORE, value);
 }

Here’s what the whole program looks like:

import java.util.*;
import java.util.prefs.*;
import javax.swing.*;
import java.awt.*;
import java.awt.event.*;

public class High {
  static JLabel highScore = new JLabel();
  static JLabel score = new JLabel();
  static Random random = new Random(new Date().getTime());
  private static final String HIGH_SCORE = “High.highScore”;

  public static void main (String args[]) {
    /* — Uncomment these lines to clear saved score
    Preferences systemNode = Preferences.systemNodeForPackage(High.class);
    systemNode.remove(HIGH_SCORE);
    */

    EventQueue.invokeLater(
      new Runnable() {
        public void run() {
          JFrame frame = new JFrame(“High Score”);
          frame.setDefaultCloseOperation(JFrame.EXIT_ON_CLOSE);
          updateHighScoreLabel(getSavedHighScore());
          frame.add(highScore, BorderLayout.NORTH);
          frame.add(score, BorderLayout.CENTER);
          JButton button = new JButton(“Play”);
          ActionListener listener = new ActionListener() {
            public void actionPerformed(ActionEvent e) {
              int next = random.nextInt(100);
              score.setText(Integer.toString(next));
              int old = getSavedHighScore();
              if (next > old) {
                Toolkit.getDefaultToolkit().beep();
                updateHighScore(next);
                updateHighScoreLabel(next);
              }
            }
          };
          button.addActionListener(listener);
          frame.add(button, BorderLayout.SOUTH);
          frame.setSize(200, 200);
          frame.setVisible(true);
        }
      }
    );
  }

  private static void updateHighScoreLabel(int value) {
    if (value == -1) {
      highScore.setText(“”);
    } else {
      highScore.setText(Integer.toString(value));
    }
  }

  private static int getSavedHighScore() {
    Preferences systemNode = Preferences.systemNodeForPackage(High.class);
    return systemNode.getInt(HIGH_SCORE, -1);
  }

  private static void updateHighScore(int value) {
    Preferences systemNode = Preferences.systemNodeForPackage(High.class);
    systemNode.putInt(HIGH_SCORE, value);
 }
}

And, here’s what the screen looks like after a few runs. The 61 score is not apt to be your high score, but it certainly could be.

You can try running the application as different users to see that they all share the same high score.

Import and Export

In the event that you wish to transfer preferences from one user to another or from one system to another, you can export the preferences from that one user/system, and then import them to the other side. When preferences are exported, they are exported into an XML formatted document whose DTD is specified by http://java.sun.com/dtd/preferences.dtd , though you don’t really need to know that. You can export either a whole subtree with the exportSubtree() method or just a single node with the exportNode() method. Both methods accept an OutputStream argument to specify where to store things. The XML document will be UTF-8 character encoded. Importing of the data then happens via the importPreferences() method, which takes an InputStream argument. From an API perspective, there is no difference in importing a system node/tree or a user node.

Adding a few lines of code to the previous example will export the newly updated high score to the file high.xml. Much of the added code is responsible for launching a new thread to save the file and for handling exceptions. There are only three lines to export the single node:

    Thread runner = new Thread(new Runnable() {
      public void run() {
        try {
          FileOutputStream fis = new FileOutputStream(“high.xml”);
          systemNode.exportNode(fis);
          fis.close();
        } catch (Exception e) {
          Toolkit.getDefaultToolkit().beep();
          Toolkit.getDefaultToolkit().beep();
          Toolkit.getDefaultToolkit().beep();
        }
      }
    });
    runner.start();

When exported, the file will look something like the following:

<?xml version=”1.0″ encoding=”UTF-8″ standalone=”no”?>
<!DOCTYPE preferences SYSTEM “http://java.sun.com/dtd/preferences.dtd”>
<preferences EXTERNAL_XML_VERSION=”1.0″>
  <root type=”system”>
    <map/>
    <node name=”<unnamed>”>
      <map>
        <entry key=”High.highScore” value=”95″/>
      </map>
    </node>
  </root>
</preferences>

Notice the root element has a type attribute that says “system “. This states the type of node it is. The node also has a name attribute valued at “<unnamed> “. Since the High class was not placed in a package, you get to work in the unnamed system node area. The entry attribute provide the current high score value, 95 in the example here, though your value could differ.

While we won’t include any import code in the example here, the way to import is just a static method call on Preferences, passing in the appropriate input stream:

  FileInputStream fis = new FileInputStream(“high.xml”);
  Preferences.importPreferences(fis);
  fis.close();

Since the XML file includes information about whether the preferences are system or user type, the import call doesn’t have to explicitly include this bit of information. Besides the typical IOExceptions that can happen, the import call will throw an InvalidPreferencesFormatException if the file format is invalid. Exporting can also throw a BackingStoreException if the data to export can’t be read correctly from the backing store.

Event Notifications

The original version of the High game updated the high score preference, then explicitly made a call to update the label on the screen. A better way to perform this action would be to add a listener to the preferences node, then a value change can automatically trigger the label to update its value. That way, if the high score is ever updated from multiple places, you won’t need to remember to add code to update the label after saving the updated value.

The two lines:

  updateHighScore(next);
  updateHighScoreLabel(next);

can become one with the addition of the right listeners.

  updateHighScore(next);

There is a PreferenceChangeListener and its associated PreferenceChangeEvent for just such a task. The listener will be notified for all changes to the associated node, so you need to check for which key-value pair was modified, as shown here.

    PreferenceChangeListener changeListener =
        new PreferenceChangeListener() {

      public void preferenceChange(PreferenceChangeEvent e) {
        if (HIGH_SCORE.equals(e.getKey())) {
          String newValue = e.getNewValue();
          int value = Integer.valueOf(newValue);
          updateHighScoreLabel(value);
        }
      }
    };
    systemNode.addPreferenceChangeListener(changeListener);

The PreferenceChangeEvent has three important properties: the key, new new value, and the node itself. The new value doesn’t have all the convenience methods of Preferences though. For example, you can’t retrieve the value as an int. Instead you must manually convert the value yourself. Here’s what the modified High class looks like:

import java.awt.*;
import java.awt.event.*;
import java.io.*;
import java.util.*;
import java.util.prefs.*;
import javax.swing.*;

public class High {
  static JLabel highScore = new JLabel();
  static JLabel score = new JLabel();
  static Random random = new Random(new Date().getTime());
  private static final String HIGH_SCORE = “High.highScore”;
  static Preferences systemNode =
  Preferences.systemNodeForPackage(High.class);

  public static void main (String args[]) {
    /* — Uncomment these lines to clear saved score
    systemNode.remove(HIGH_SCORE);
    */

    PreferenceChangeListener changeListener =
        new PreferenceChangeListener() {

      public void preferenceChange(PreferenceChangeEvent e) {
        if (HIGH_SCORE.equals(e.getKey())) {
          String newValue = e.getNewValue();
          int value = Integer.valueOf(newValue);
          updateHighScoreLabel(value);
        }
      }
    };
    systemNode.addPreferenceChangeListener(changeListener);

    EventQueue.invokeLater(
      new Runnable() {
        public void run() {
          JFrame frame = new JFrame(“High Score”);
          frame.setDefaultCloseOperation(JFrame.EXIT_ON_CLOSE);
          updateHighScoreLabel(getSavedHighScore());
          frame.add(highScore, BorderLayout.NORTH);
          frame.add(score, BorderLayout.CENTER);
          JButton button = new JButton(“Play”);
          ActionListener listener = new ActionListener() {
            public void actionPerformed(ActionEvent e) {
              int next = random.nextInt(100);
              score.setText(Integer.toString(next));
              int old = getSavedHighScore();
              if (next > old) {
                Toolkit.getDefaultToolkit().beep();
                updateHighScore(next);
              }
            }
          };
          button.addActionListener(listener);
          frame.add(button, BorderLayout.SOUTH);
          frame.setSize(200, 200);
          frame.setVisible(true);
        }
      }
    );
  }

  private static void updateHighScoreLabel(int value) {
    if (value == -1) {
      highScore.setText(“”);
    } else {
      highScore.setText(Integer.toString(value));
    }
  }

  private static int getSavedHighScore() {
    return systemNode.getInt(HIGH_SCORE, -1);
  }

  private static void updateHighScore(int value) {
    systemNode.putInt(HIGH_SCORE, value);
    // Save XML in separate thread
    Thread runner = new Thread(new Runnable() {
      public void run() {
        try {
          FileOutputStream fis = new FileOutputStream(“high.xml”);
          systemNode.exportNode(fis);
          fis.close();
        } catch (Exception e) {
          Toolkit.getDefaultToolkit().beep();
          Toolkit.getDefaultToolkit().beep();
          Toolkit.getDefaultToolkit().beep();
        }
      }
    });
    runner.start();
  }
}

In addition to the PreferenceChangeListener/Event class pair, there is a NodeChangeListener and NodeChangeEvent combo for notification of preference changes. However, these are for notification nodes additions and removals, not changing values of specific nodes. Of course, if you are writing something like a Preferences viewer, clearly you’d want to know if/when nodes appear and disappear so these classes may be of interest, too.

The whole Preferences API can be quite handy to store data beyond the life of your application without having to rely on a database system. For more information on the API, see the article Sir, What is Your Preference?

The enhanced for-loop is a popular feature introduced with the Java SE platform in version 5.0. Its simple structure allows one to simplify code by presenting for-loops that visit each element of an array/collection without explicitly expressing how one goes from element to element.

Because the old style of coding didn’t become invalid with the new for-loop syntax, you don’t have to use an enhanced for-loop when visiting each element of an array/collection. However, with the new style, one’s code would typically change from something like the following:

for (int i=0; i<array.length; i++) {
    System.out.println(“Element: ” + array[i]);
}

to the newer form:

for (String element : array) {
    System.out.println(“Element: ” + element);
}

Assuming “array” is defined to be an array of String objects, each element is assigned to the element variable as it loops through the array. These basics of the enhanced for-loop were covered in an earlier Tech Tip: The Enhanced For Loop, from May 5, 2005.

If you have a class called Colony which contains a group of Penguin objects, without doing anything extra to get the enhanced for-loop to work, one way you would loop through each penguin element would be to return an Iterator and iterate through the colony. Unfortunately, the enhanced for-loop does not work with Iterator , so the following won’t even compile:

// Does not compile
import java.util.*;
public class BadColony {
  static class Penguin {
    String name;
    Penguin(String name) {
      this.name = name;
    }
    public String toString() {
      return “Penguin{” + name + “}”;
    }
  }

  Set<Penguin> set = new HashSet<Penguin>();

  public void addPenguin(Penguin p) {
    set.add(p);
  }

  public Iterator<Penguin> getPenguins() {
    return set.iterator();
  }

  public static void main(String args[]) {
    Colony colony = new Colony();
    Penguin opus = new Penguin(“Opus”);
    Penguin chilly = new Penguin(“Chilly Willy”);
    Penguin mumble = new Penguin(“Mumble”);
    Penguin emperor = new Penguin(“Emperor”);
    colony.addPenguin(opus);
    colony.addPenguin(chilly);
    colony.addPenguin(mumble);
    colony.addPenguin(emperor);
    Iterator<Penguin> it = colony.getPenguins();
// The bad line of code:
    for (Penguin p : it) {
      System.out.println(p);
    }
  }
}

You cannot just pass an Iterator into the enhanced for-loop. The 2nd line of the following will generate a compilation error:

    Iterator<Penguin> it = colony.getPenguins();
    for (Penguin p : it) {

The error:

BadColony.java:36: foreach not applicable to expression type
    for (Penguin p : it) {
                     ^
1 error

In order to be able to use your class with an enhanced for-loop, it does need an Iterator , but that Iterator must be provided via the Iterable interface:

public interface java.lang.Iterable {
    public java.util.Iterator iterator();
}

Actually, to be more correct, you can use a generic T , allowing the enhanced for-loop to avoid casting, returning the designated generic type, instead of just a plain old Object .

public interface java.lang.Iterable<T> {
    public java.util.Iterator<T> iterator();
}

It is this Iterable object which is then provided to the enhanced for-loop. By making the Colony class implement Iterable , and having its new iterator() method return the Iterator that getPenguins() provides, you’ll be able to loop through the penguins in the colony via an enhanced for-loop.

By adding the proper implements clause:

public class Colony implements Iterable<Colony.Penguin> {


You then get your enhanced for-loop for the colony:

    for (Penguin p : colony) {

Here’s the updated Colony  class with the corrected code:

import java.util.*;

public class Colony implements Iterable<Colony.Penguin> {

  static class Penguin {
    String name;
    Penguin(String name) {
      this.name = name;
    }
    public String toString() {
      return “Penguin{” + name + “}”;
    }
  }

  Set<Penguin> set = new HashSet<Penguin>();

  public void addPenguin(Penguin p) {
    set.add(p);
  }

  public Iterator<Penguin> getPenguins() {
    return set.iterator();
  }

  public Iterator<Penguin> iterator() {
    return getPenguins();
  }

  public static void main(String args[]) {
    Colony colony = new Colony();
    Penguin opus = new Penguin(“Opus”);
    Penguin chilly = new Penguin(“Chilly Willy”);
    Penguin mumble = new Penguin(“Mumble”);
    Penguin emperor = new Penguin(“Emperor”);
    colony.addPenguin(opus);
    colony.addPenguin(chilly);
    colony.addPenguin(mumble);
    colony.addPenguin(emperor);
    for (Penguin p : colony) {
      System.out.println(p);
    }
  }
}

Running the code produces the following output:

  > java Colony

  Penguin{Chilly Willy}
  Penguin{Mumble}
  Penguin{Opus}
  Penguin{Emperor}

Keep in mind that the individual penguins are internally kept in a Set type collection so the returned order doesn’t necessarily match the insertion order, which in this case it doesn’t.

Remember to genericize the implements clause for the class “implements Iterable<T> ” and not just say “implements Iterable “. With the latter, the enhanced for-loop will only return an Object for each element.

For more information on the enhanced for-loop, please see the Java Programming Language guide from JDK 1.5.

Iterating over a collection is uglier than it needs to be. Consider the following method, which takes a collection of timer tasks and cancels them:

    void cancelAll(Collection<TimerTask> c) {
        for (Iterator<TimerTask> i = c.iterator(); i.hasNext(); )
            i.next().cancel();
    }

The iterator is just clutter. Furthermore, it is an opportunity for error. The iterator variable occurs three times in each loop: that is two chances to get it wrong. The for-each construct gets rid of the clutter and the opportunity for error. Here is how the example looks with the for-each construct:

    void cancelAll(Collection<TimerTask> c) {
        for (TimerTask t : c)
            t.cancel();
    }

When you see the colon (:) read it as “in.” The loop above reads as “for each TimerTask t in c.” As you can see, the for-each construct combines beautifully with generics. It preserves all of the type safety, while removing the remaining clutter. Because you don’t have to declare the iterator, you don’t have to provide a generic declaration for it. (The compiler does this for you behind your back, but you need not concern yourself with it.)

Here is a common mistake people make when they are trying to do nested iteration over two collections:

    List suits = …;
    List ranks = …;
    List sortedDeck = new ArrayList();

    // BROKEN – throws NoSuchElementException!
    for (Iterator i = suits.iterator(); i.hasNext(); )
        for (Iterator j = ranks.iterator(); j.hasNext(); )
            sortedDeck.add(new Card(i.next(), j.next()));

Can you spot the bug? Don’t feel bad if you can’t. Many expert programmers have made this mistake at one time or another. The problem is that the next method is being called too many times on the “outer” collection (suits). It is being called in the inner loop for both the outer and inner collections, which is wrong. In order to fix it, you have to add a variable in the scope of the outer loop to hold the suit:

    // Fixed, though a bit ugly
    for (Iterator i = suits.iterator(); i.hasNext(); ) {
        Suit suit = (Suit) i.next();
        for (Iterator j = ranks.iterator(); j.hasNext(); )
            sortedDeck.add(new Card(suit, j.next()));
    }

So what does all this have to do with the for-each construct? It is tailor-made for nested iteration! Feast your eyes:

    for (Suit suit : suits)
        for (Rank rank : ranks)
            sortedDeck.add(new Card(suit, rank));

The for-each construct is also applicable to arrays, where it hides the index variable rather than the iterator. The following method returns the sum of the values in an int array:

    // Returns the sum of the elements of a
    int sum(int[] a) {
        int result = 0;
        for (int i : a)
            result += i;
        return result;
    }

So when should you use the for-each loop? Any time you can. It really beautifies your code. Unfortunately, you cannot use it everywhere. Consider, for example, the expurgate method. The program needs access to the iterator in order to remove the current element. The for-each loop hides the iterator, so you cannot call remove. Therefore, the for-each loop is not usable for filtering. Similarly it is not usable for loops where you need to replace elements in a list or array as you traverse it. Finally, it is not usable for loops that must iterate over multiple collections in parallel. These shortcomings were known by the designers, who made a conscious decision to go with a clean, simple construct that would cover the great majority of cases.

Before enabling HTTP file upload on your server, one important thing that you must consider is security, as improper design and configuration will make your server vulnerable to attacks.

For example, the PHP file upload script and JSP file upload script that were covered earlier are not secure. One problem is that we have not checked what the user entered in the optional filename text box. This gives malicious users the chance to modify the server’s files (e.g. system files or password files). For example, if a malicious user enters a path such as “../password/password.dat” in the optional filename text box, our PHP and JSP script will save the uploaded file to the destination “/file_uploads/../password/password.dat”, which is actually the path “/password/password.dat”.

Here are a few security tips that may be useful to you. We will only provide some brief descriptions here. For more details, please refer to other sources.

• 
  

  Check all information provided by the client to ensure that it is safe. For example:

  
  
  
  
  • 
    

    The HTTP request received includes a MIME type that describes what the uploaded file contains. A malicious user can provide a wrong value to trick you to think that the uploaded file is of another type. Hence, you should not rely on the MIME type included in the HTTP request but should perform a check by your own at the server-side. For instance, the photo album example covered earlier does not perform any checks to ensure the uploaded files are really image files. To enhance security, we can include a check on the uploaded files using the PHP function getimagesize() at the server-side. If getimagesize() returns false, that means the uploaded file is not a valid image file and it should be rejected.

    
    
  • 
    

    The HTTP request received includes the uploaded file’s original file name at the client-side. A malicious user can provide an unsafe value to trick you to modify system or password files. This problem is similar to the one described in the second paragraph of this section, so we will not describe it once more.
    In addition, you should prepare for the situation that the file name contains special characters that are not allowed to appear in file names or non-English characters. Make sure your WAP/web application will not crash or be left in an erroneous state when such situations occur.

  
  
• 
  

  Set a file size limit so that the user cannot upload files that are too large or too small.

  
  
• 
  

  Do not run web servers or application servers with the administrator account. Create and configure an account that is specifically for their use. Limit the file access permissions of the account so that even if your WAP/web application has security holes, the OS will not allow it to work with system files or files of other users.

  
  
• 
  

  Make sure your WAP/web application does not reveal too much information to the user when an error occurs. The information revealed can help a malicious user find ways to attack your system.

  
  
• 
  

  Log down the details (such as the time, the client’s IP address and the user name) of file uploads and other related events. Although the logs only tell you what has happened, they can help you check what types of attacks have been made against your server and whether there were any successful attacks.

Below shows a JSP file upload script that is used to print out the name-value pair received from the earlier XHTML MP document and save the uploaded file to a certain location on the WAP server. Remember to change the action attribute of the <form> element in the earlier XHTML MP document from file_upload.php to file_upload.jsp for this example to work.

Below shows a PHP file upload script that is written to handle the form data submitted from the earlier XHTML MP document. The PHP script prints out the information obtained from the HTTP request and saves the uploaded file to the “/file_uploads” directory of the WAP server.

Unlike PHP, Java Servlet and JSP do not have build-in mechanisms for handling form-based file uploads. One solution to this problem is to implement a function yourself to extract uploaded files contained in an HTTP request. However, a better choice is to make use of a third-party library that can help us handle file uploads.

One robust library available is the Apache Jakarta Commons FileUpload package. It is open-source and can be downloaded free of charge over the Internet. We will demonstrate how to use the Apache Jakarta Commons FileUpload package to extract uploaded files submitted from a form. The techniques are the same for HTML and XHTML. If you are not familiar with JSP or Java Servlet, you may want to read some introductory tutorials before going through this section.

At the time of writing, the most up-to-date version of the Apache Jakarta Commons FileUpload library is 1.1.1. So, we assume you are using Commons FileUpload 1.1.1 in this tutorial. For other versions of Commons FileUpload, the procedures may be slightly different but the principle is the same.

Downloading the Apache Jakarta Commons FileUpload and Commons IO Libraries

To download the Apache Jakarta Commons FileUpload library, go to the home page of the Apache Jakarta Commons FileUpload project and navigate to the download section. The binaries are available in two file formats: zip format and tar-gzip format. Download either one of them and uncompress the file. Then go to the home page of the Apache Jakarta Commons IO project and repeat the same steps. We need the Commons IO library since Commons FileUpload uses it internally. Now you have two JAR files, “commons-fileupload-version.jar” and “commons-io-version.jar”, where version is the version number. At the time of writing, the latest version of the Commons FileUpload library and that of the Commons IO library are 1.1.1 and 1.2 respectively. So, the JAR files we obtain are “commons-fileupload-1.1.1.jar” and “commons-io-1.2.jar”.

Installing Apache Jakarta Commons FileUpload and Commons IO into a Servlet/JSP Container Like Tomcat

Next, we need to install the Apache Jakarta Commons FileUpload library and the Apache Jakarta Commons IO library into a Servlet/JSP container such as Apache Tomcat. To do this, copy the JAR files “commons-fileupload-1.1.1.jar” and “commons-io-1.2.jar” to the /WEB-INF/lib/ directory in the document root of your web application.

Note that JAR libraries stored in /WEB-INF/lib/ will be available to the containing web application only. If you want to share the libraries among all web applications installed in Tomcat (suppose you are using Tomcat 5 or Tomcat 4), the JAR files should be copied to the $CATALINA_HOME/shared/lib/ directory, where $CATALINA_HOME is the root of your Tomcat installation.

Checking If an HTTP Request is Encoded in Multipart Format

Now that you have installed the Apache Jakarta Commons FileUpload library, you can start writing the code. First, we have to make sure the HTTP request is encoded in multipart format. This can be done using the static method isMultipartContent() of the ServletFileUpload class of the org.apache.commons.fileupload.servlet package:

if (ServletFileUpload.isMultipartContent(request)){
  // Parse the HTTP request…
}

In the above Java code snippet, request is a javax.servlet.http.HttpServletRequest object that encapsulates the HTTP request. It should be very familiar to you if you know Java Servlet or JSP.

Parsing Form Data with Java Servlet / JSP

Second, we will parse the form data contained in the HTTP request. Parsing the form data is very straightforward with the Apache Jakarta Commons FileUpload library:

ServletFileUpload servletFileUpload = new ServletFileUpload(new DiskFileItemFactory());
List fileItemsList = servletFileUpload.parseRequest(request);

(In the above Java code snippet, DiskFileItemFactory is a class contained in the org.apache.commons.fileupload.disk package and List is an interface contained in the java.util package.)

If everything works fine, fileItemsList will contain a list of file items that are instances of FileItem of the org.apache.commons.fileupload package. A file item may contain an uploaded file or a simple name-value pair of a form field. (More details about FileItem will be provided later.)

By default, the ServletFileUpload instance created by the above Java code uses the following values when parsing the HTTP request:

• 
  

  Size threshold = 10,240 bytes. If the size of a file item is smaller than the size threshold, it will be stored in the memory. Otherwise it will be stored in a temporary file on disk.

  
  
• 
  

  Maximum HTTP request body size = -1, which means the server will accept HTTP request bodies of any size.

  
  
• 
  

  Repository = System default temp directory, whose value can be found by the Java code System.getProperty(“java.io.tmpdir”). Temporary files will be stored there.

If you do not like the default settings, you can change them using the methods setSizeThreshold() and setRespository() of the DiskFileItemFactory class and the setSizeMax() method of the ServletFileUpload class, like this:

DiskFileItemFactory diskFileItemFactory = new DiskFileItemFactory();
diskFileItemFactory.setSizeThreshold(40960); /* the unit is bytes */

File repositoryPath = new File(“/temp”);
diskFileItemFactory.setRepository(repositoryPath);

ServletFileUpload servletFileUpload = new ServletFileUpload(diskFileItemFactory);
servletFileUpload.setSizeMax(81920); /* the unit is bytes */

(In the above Java code snippet, File is a class of the java.io package.)

If the size of the HTTP request body exceeds the maximum you set, the SizeLimitExceededException exception (fully qualified name: org.apache.commons.fileupload.FileUploadBase.SizeLimitExceededException) will be thrown when you call the parseRequest() method:

try {
  List fileItemsList = servletFileUpload.parseRequest(request);
  /* Process file items… */
}
catch (SizeLimitExceededException ex) {
  /* The size of the HTTP request body exceeds the limit */
}

Iterating through File Items

The following example demonstrates how to upload a file from a Nokia 6230 cell phone. Here is the XHTML MP document of the example. As XHTML MP is compatible with HTML/XHTML, this XHTML MP document can also be opened with web browsers such as Microsoft Internet Explorer and Mozilla Firefox.

In this section, we will introduce to you how to handle form-based file uploads with a PHP script. The techniques are the same for HTML and XHTML. At the time of writing, the latest version of PHP is 5.2.0. So, we assume you are using PHP 5.2.0 in this tutorial. For other versions of PHP, the procedures should be similar. If you are not familiar with PHP, you may want to read some introductory tutorials before going through this section.

Parsing Form Data and Getting Information about the Uploaded File with PHP

To extract an uploaded file from an HTTP request, we need to parse the form data that is encoded in the “multipart/form-data” format. In PHP, the form data in an HTTP request is automatically parsed. The PHP engine stores the information of the uploaded files in the $_FILES array.

Now let’s say the name attribute value of the <input type=”file”> element in a certain HTML/XHTML/XHTML MP document is myFile. To obtain the information about the uploaded file, use the following lines of PHP script:

/* Get the size of the uploaded file in bytes. */
$fileSize = $_FILES[‘myFile’][‘size’];

/* Get the name (including path information) of the temporary file created by PHP that contains the same contents as the uploaded file. */
$tmpFile = $_FILES[‘myFile’][‘tmp_name’];

/* Get the name of the uploaded file at the client-side. Some browsers include the whole path here (e.g. e:\files\myFile.txt), so you may need to extract the file name from the path. This information is provided by the client browser, which means you should be cautious since it may be a wrong value provided by a malicious user. */
$fileName = $_FILES[‘myFile’][‘name’];

/* Get the content type (MIME type) of the uploaded file. This information is provided by the client browser, which means you should be cautious since it may be a wrong value provided by a malicious user. */
$contentType = $_FILES[‘myFile’][‘type’];

Nokia cell phones such as Nokia 6230 determine the content type (MIME type) of the file to be uploaded by its file extension. The following table lists some of the file extensions that are recognized by Nokia 6230:

File extension	Content type / MIME type
.jpg	image/jpeg
.gif	image/gif
.png	image/png
.wbmp	image/vnd.wap.wbmp
.txt	text/plain

If the Nokia 6230 cell phone does not recognize a file extension, it will specify “application/octet-stream” as the content type / MIME type of the file in the HTTP request.