Lecture Six

By : Eyob Gebretinsae

1
 Beyond the typically small persistent storage managed by MIDP’s
record store mechanism, devices may have additional persistent
data storage mechanisms that can be made available to Java ME
applications.
 Large file systems can be found on devices that accept plug-in flash
memory cards.
 The File Connection Optional Package provides an API to access
these file systems.
 The record store mechanism of MIDP is inefficient for handling
large-capacity storage.
 The persistent storage on these cards is accessed as a file system,
instead of a database, with directories and files.


2
 This optional API is contained in the
javax.microedition.io.file package.
 This optional package is implemented on top of CLDC.
 It is always a good idea to make sure an optional API is

available on a device before attempting to use it.

 If you want to confirm that the FileConnection optional API

is available on a device, check for the system property called

microedition.io.file.FileConnection.version.
String currentVersion = System.getProperty
("microedition.io.file.FileConnection.
version");
 You can also use the returned version to make sure your

code is compatible.
 Null is returned if the API is not available.

3
 You perform read and write operations through the input
and output stream classes from the java.io package.
 To obtain a stream to a file in the file system, you first need

to have an opened file connection.

 For this, you will need to use the File Connection optional

API.
 The main interface of this API is the FileConnection

interface.
 You obtain an instance of a FileConnection by using a

method of the javax.microedition.io.Connector class.

 This class is part of the Generic Connection

Framework(GCF) in CLDC.
 GCF is used primarily to make connections through a

network or a communications port.

4
 The following static method of the Connector class can return a
FileConnection instance:
public static Connection open(String URL,
int mode) throws IOException,
IllegalArgumentException,
ConnectionNotFoundException,
SecurityException
 The URL to obtain a file connection will always start with

“file:///”, indicating that a file is accessed on the local host.

 The full syntax for the URL is actually “file://<hostname.

 The mode indicates the type of access you want for the file

connection.
 You can use Connector.READ, Connector.WRITE, or

Connector.READ_WRITE.
5
 E.g, you may get an input stream to an existing abc.txt file on an
SD card using the following:
 FileConnection fc = (FileConnection)

Connector.open("file:/// SDCard
/abc.txt",Connector.READ);
InputStream is = fc.openInputStream();
 You can then use the InputStream for reading the file.
 The FileConnection interface has five methods for obtaining a

stream:
 DataInputStream openDataInputStream()
 DataOutputStream openDataOutputStream()
 InputStream openInputStream()
 OutputStream openOutputStream()
 OutputStream openOutputStream(long Offset)
6
 The second variation of openOutputStream() allows you to
specify a byte offset to start writing to the file.
 File or Directory
 An open FileConnection can be referring to either a directory
or a file.
 You can determine if the connection is associated with a

directory via the following method:

public boolean isDirectory()
 Some file systems, such as Win32, support hidden files.

Hidden files do not appear on regular directory listings, and

are often used for system files.
 You can determine whether a file or directory is hidden by

calling the following method: public isHidden()

 On a file system that does not support hidden files,

isHidden() always returns false.

7
 You can also control the hidden attribute of a file on file
systems that support it, by using this method:
public void setHidden(boolean
hiddenFlag)
 Setting hiddenFlag to true will make the file hidden,

while a false value will make it visible.

 This method has no effect on file systems that do not

support hidden files nor on file systems where you must

rename the file to make files hidden.

8
 Some file attributes may prevent you from reading or
writing to a file. You can determine whether a file can be
read by using this method:
public boolean canRead()
 Or find out if a file can be written to using the following:

public boolean canWrite()

 To change the read or write attribute of a file on a file

system that supports it, use this:

public void setReadable(boolean
readable)throws IOException
public void setWriteable(boolean
readable) throws IOException

9
 Your application may need to determine the available space
on a file system associated with a FileConnection instance.
public long availableSize()
 This returns the total available space in bytes in the entire file

system. On plug-in memory cards, this can be up to gigabytes

of data.
 There is another method to find out the size of the storage

area already used up:

public long usedSize()
 By adding up the value returned from availableSize() and

usedSize(), you can figure out the total size of the file system.

10
 If you only want to find out the size of the specific file
associated with the current FileConnection instance, use
the following method:
public long fileSize()
 If the FileConnection instance refers to a directory, you

can find out the total size of all the files in the directory
by calling the following method:
public long directorySize()

11
 To create a new file, you first have to use Connector.open()
with the new file name and Connector.WRITE mode.
 A FileConnection will be returned, but the file does not yet

exist.
 You can confirm its nonexistence by calling

boolean exists() throws SecurityException,

IllegalModeException,
ConnectionClosedException
 To create the file, you call

public void create() thows IOException

 Creating a new directory is similar. Use Connector.open()

with the new directory name.

 Then call the mkdir() method on the returned FileConnection:
12
 public void mkdir() throws IOException
 Note that it is not possible to create a directory using the

create() call for a file using a URL such as “file:///mydir/”.

Renaming and Deleting Files and Directories
 To delete a file or directory, you need to first open it with
Connector.WRITE mode enabled, then call the method:
public void delete() throws IOException
 You should immediately call close() on the FileConnection

after a delete(). The FileConnection is no longer valid once

the underlying file has been deleted.
 To rename file or directory,open it with Connector.WRITE mode
enabled, and then call the rename() method of the FileConnection
instance with the new name:
public void rename(String newName) throws
IOException 13
Listing Directory Content
 When you have a FileConnection to a directory, you can
obtain an Enumeration of its content (files and subdirectory)
using this method:
 Enumeration list() throws IOException
 Enumeration list(String filter, boolean

includeHidden) throws IOException

 The returned Enumeration contains objects of string type. Each

object in the enumeration is the name of a file or directory.

 If the object is a directory, the name will end with /.
 The second form of list() uses a filter that can contain the *

(asterisk) wildcard character.

 E.g, a filter value of “*.png” will select only the PNG

graphics files in the directory.

14
 Note that the string from a list()-returned Enumeration does
not contain full path information, or any of the “file:///”
URL preamble.
 However, if you actually need the full URL, you can call this

method to get the complete path and preamble:

public String getPath()
 By appending the string from the list()-returned

Enumeration to the string returned from the preceding

method, you end up with a full URL.
 If you already have a FileConnection open, you can always

get the complete URL associated it by calling the following

method: public String getURL()
15
To get just the name of the file or directory, without the path
and URL preamble, you can call
public String getName()
 Listening for Card Insertion and Removal
 A user may insert or remove flash memory card at any time,
which will affect the availability of file systems on a device.
 The File Connection API supports a JavaBeans-style listener

mechanism. The listener interface is

javax.microedition.io.file.FileSystemListener
 Because a device may have multiple file systems (for
example, built-in flash memory and a slot for plugin cards), a
central registry class is used to manage the listeners.
 This central registry is the

javax.microedition.io.file.FileSystemRegistry
class.
16
 You can add and remove file system listeners by using the
two static methods of FileSystemRegistry:

 public static boolean

addFileSystemListener(FileSystemListener
listener) throws SecurityException,
NullPointerException

 public static boolean

removeFileSystemListener
(FileSystemListener listener) throws
NullPointerException
 The returned boolean value on these two methods will

indicate success of the operation.

17
 The FileSystemListener interface has only a single
method:
 void rootChanged(int state, String

rootName)
 This method is called whenever there is a change in the

set of file systems available.

 The state value is either

FileSystemListener.ROOT_ADDED (for insertion of

memory card) or
 FileSystemListener.ROOT_REMOVED (when

memory card is removed). The rootName will provide

 The name of the root used to access the file system.

18
 Personal Information Management (PIM) are databases
 Many devices, especially phones, have the ability to

maintain lists of phone numbers and names.

 Some devices also store addresses, e-mails, events, to-do

lists, and other personal information.

 This PIM data is stored in PIM databases.
 Most devices will have built-in applications that manage

the PIM data.

 Until recently, there was no direct way of accessing this

information from your MIDP application.

 A device vendor may now expose access to its PIM

databases through the PIM Optional Package

19
20
 You should check to see if the PIM Optional Package is
available on a device before attempting to use it.
 String currentVersion = System.
getProperty("microedition.pim.version")
 You should also use the returned version to make sure your code
is version compatible.
 The API centers around the PIM abstract class. You cannot
instantiate this class with the new operator.
 However, there is a class factory method to obtain the one and
only instance:
 public static PIM getInstance()
 You can access the PIM lists once you have the singleton
instance.

21
 A PIM list can be obtained using one of these
openPIMList() methods:
 public PIMList openPIMList(int

pimListType, int mode) throws

PIMException
 public PIMList openPIMList(int

pimListType, int mode, String name)

throws PIMException
 The pimListType can contain PIM.CONTACT_LIST,

PIM.EVENT_LIST, or PIM.TODO_LIST.
 The access mode can be PIM.READ_ONLY,

PIM.READ_WRITE, or PIM.WRITE_ONLY.

22
 Once you have a list opened, you can start accessing its
content.
 The openPIMList() call returns a PIMList. The

javax.microedition.pim.PIMList interface is the super

interface of ContactList, EventList, and ToDoList.
 You need to cast it to the expected type before accessing

the list, for example:

 ContactList clist =

(ContactList)pimInst.openPIMList( PIM.C
ONTACT_LIST, PIM.READ_WRITE);

23
 All the records in a list can be accessed via an
Enumeration (java.util.Enmeration) of PIMItems.
 You can obtain the Enumeration using one of the

items() methods on the PIMList:

 public Enumeration items() throws

PIMException
 public Enumeration items(PIMItem

matchingItem) throws PIMException

 public Enumeration items(String

matchingValue) throws PIMException

 The second and third form in the preceding list will

both return a subset of the items in a list.

24
 You can classify a list of items by categories.
 A category is a just a string. E.g, a “personal” category can be
used to flag all the personal contacts in the content list, while a
“business” category is used for business contacts.
 To obtain all the list items in a particular category, you can use
the following:
 public Enumeration itemsByCategory (String
category) throws PIMException
 To get a list of categories supported by the device, call
 String [] getCategories() throws
PIMException
 If you get a zero-length array in return, you know that either the
device does not support categories or the user hasn’t defined
any.
25
 Once you’ve determined that the device supports categories,
you can add new categories using the following:
 public void addCategory(String category)

throws PIMException
 This method will never add the same category twice. It will

return without throwing an exception if the specified

category already exists.
 To delete a category, use this method:

public void deleteCategory(String

category, boolean deleteUnassignedItems)
 Note that some items may end up having no category

assigned once a category is deleted.

26
 Set the deleteUnassignedItems flag to true if you want
these items deleted from the list.
 The deleteCategory() method will return without throwing

an exception even if the category specified does not exist.

 It will, however, throw a PIMException if categories are

not supported on the device.

 A category can be renamed using the following method:

public void renameCategory(String

currentCategoryName, String
newCategoryName) throws PIMException

27