com.funambol.mail
Interface Store

All Known Implementing Classes:
NokiaFP2RMSStore, RMSStore

public interface Store

This interface defines a hierarchical object store and its access protocol. It can be used to store and retrieve Folder items and the contained child items.

A Folder child is represented as a generic Serializable object in order to store any kind of data, including:

  • AccountFolder items;
  • Folder items;
  • Message items.

  • Field Summary
    static int LATEST_VERSION
              Latest version
    static int VERSION_101
              Store available versions
    static int VERSION_102
               
    static int VERSION_103
               
    static int VERSION_104
               
    static int VERSION_105
               
     
    Method Summary
     int addChild(java.lang.String path, RmsRecordItem child)
              This method add a new child to a Folder.
     Folder addFolder(Folder folder)
              Add a new Folder to the Store.
     int countChilds(java.lang.String path)
              This method returns the count of childs in a Folder.
     int countChilds(java.lang.String path, char prefix)
              This method returns the count of childs in a Folder.
     Folder[] findFolders(java.lang.String path)
              Retrieves a Folder in this Store that matches the provided substring.
     java.lang.String[] getChildIDs(java.lang.String path)
              This method returns the array of the childs IDs contained in a Folder.
     ChildrenEnumeration getChildren(java.lang.String path)
              Get the ChildrenEnumeration related to the given path.
     Folder getFolder(java.lang.String path)
              Retrieves a Folder object by path.
     Folder getFolder(java.lang.String path, boolean lightFolder)
              Retrieves a Folder object by path.
     int getVersion()
              This method gets the version of the Store which is currently being used on the device.
     void init(boolean reset)
              Initialize the store.
     Folder[] list()
              Retrieves the list of all the folders directly under this Store.
     Folder[] list(java.lang.String path)
              Returns the list of the subfolders contained under the specified Folder.
     RmsRecordItem readChild(java.lang.String path, java.lang.String childId)
              This method reads a Folder from the Store, using the child id.
     java.io.DataInputStream readChildBytes(java.lang.String path, java.lang.String childId)
              This method returns the InputStream of a Folder child.
     void removeChild(java.lang.String path, java.lang.String childId)
              This method removes a Folder child from the Store.
     boolean removeFolder(Folder folder, boolean recursive)
              Removes a Folder from the record store.
     void removeFolder(java.lang.String folderPath)
              Recursively removes a Folder given the Folder name
     java.lang.String retrieveSubfolderID(java.lang.String subfolderPath, java.lang.String parentPath)
              Retrieve a subfolder from a folder record store and return its record id.
     void setVersion(int version)
              This method sets the version of the Store which is currently being used on the device.
     void updateChild(java.lang.String path, RmsRecordItem child)
              This method updates an existing Folder child in the Store.
     

    Field Detail

    VERSION_101

    static final int VERSION_101
    Store available versions

    See Also:
    Constant Field Values

    VERSION_102

    static final int VERSION_102
    See Also:
    Constant Field Values

    VERSION_103

    static final int VERSION_103
    See Also:
    Constant Field Values

    VERSION_104

    static final int VERSION_104
    See Also:
    Constant Field Values

    VERSION_105

    static final int VERSION_105
    See Also:
    Constant Field Values

    LATEST_VERSION

    static final int LATEST_VERSION
    Latest version

    See Also:
    Constant Field Values
    Method Detail

    init

    void init(boolean reset)
              throws MailException
    Initialize the store.

    Parameters:
    reset - If true, erase and re-create all the store.
    Throws:
    MailException

    list

    Folder[] list()
    Retrieves the list of all the folders directly under this Store.

    Returns:
    An array of folders, or null if the store is empty.

    list

    Folder[] list(java.lang.String path)
                  throws MailException
    Returns the list of the subfolders contained under the specified Folder.

    Parameters:
    path - The path of the parent Folder.
    Returns:
    An array of folders, or null if path has no subfolders.
    Throws:
    MailException - If the path is not valid.

    addFolder

    Folder addFolder(Folder folder)
                     throws MailException
    Add a new Folder to the Store.

    Parameters:
    folder - The Folder item to be stored.
    Returns:
    The added Folder reference
    Throws:
    MailException - If an error occurs on the store (e.g. no space left).

    removeFolder

    boolean removeFolder(Folder folder,
                         boolean recursive)
                         throws MailException
    Removes a Folder from the record store. The removal can be recursive, if the Folder contains subfolders and the removal is not recursive, the method will fail.

    Parameters:
    folder - The Folder to be removed. Use getFolder to retrieve the Folder from its path.
    recursive - Perform a recursive removal.
    Returns:
    true if the Folder has been actually deleted, false if the Folder did not exist.
    Throws:
    MailException - If an error occurs on the store.

    removeFolder

    void removeFolder(java.lang.String folderPath)
                      throws MailException
    Recursively removes a Folder given the Folder name

    Parameters:
    folderPath - the path of the Folder to be removed
    Throws:
    MailException - if a storage error occurs

    getFolder

    Folder getFolder(java.lang.String path)
                     throws MailException
    Retrieves a Folder object by path.

    Parameters:
    path - The path to the Folder in the device's file system
    Returns:
    The Folder object.
    Throws:
    MailException - If an error occurs accessing the Store.

    getFolder

    Folder getFolder(java.lang.String path,
                     boolean lightFolder)
                     throws MailException
    Retrieves a Folder object by path.

    Parameters:
    path - The path to the Folder in the device's file system
    lightFolder - If true return the Folder item without reading its properties (e.g. role, creation date). It doesn't check if it really exists in the Store.
    Returns:
    The Folder object.
    Throws:
    MailException - If an error occurs accessing the Store.

    findFolders

    Folder[] findFolders(java.lang.String path)
    Retrieves a Folder in this Store that matches the provided substring.

    Parameters:
    path - The partial path in the device's file system to the searched Folder.
    Returns:
    A list of Folder objects whose path matches the provided substring, or null if there are no matches.

    retrieveSubfolderID

    java.lang.String retrieveSubfolderID(java.lang.String subfolderPath,
                                         java.lang.String parentPath)
    Retrieve a subfolder from a folder record store and return its record id.

    Parameters:
    subfolderPath - The path to the subfolder
    parentPath - The path to the parent folder
    Returns:
    The folder ID, null if it's not found

    getChildIDs

    java.lang.String[] getChildIDs(java.lang.String path)
                                   throws MailException
    This method returns the array of the childs IDs contained in a Folder.

    Parameters:
    path - The complete path of the Folder.
    Returns:
    An array containing all the childs Ids, or null if the Folder is empty.
    Throws:
    MailException - If an error occurs accessing the Store.

    readChild

    RmsRecordItem readChild(java.lang.String path,
                            java.lang.String childId)
                            throws MailException
    This method reads a Folder from the Store, using the child id.

    Parameters:
    path - The complete path of the Folder containing the child.
    childId - The child unique ID.
    Returns:
    The RmsRecordItem object corresponding to the childId.
    Throws:
    MailException - If an error occurs accessing the Store.

    readChildBytes

    java.io.DataInputStream readChildBytes(java.lang.String path,
                                           java.lang.String childId)
                                           throws MailException
    This method returns the InputStream of a Folder child.

    Parameters:
    path - The complete path of the Folder containing the child.
    childId - The child unique ID.
    Returns:
    The DataInputStream corresponding to the childId.
    Throws:
    MailException - If an error occurs accessing the Store.

    getChildren

    ChildrenEnumeration getChildren(java.lang.String path)
                                    throws MailException
    Get the ChildrenEnumeration related to the given path.

    Parameters:
    path - The path for which the ChildrenEnumeration shall be returned.
    Returns:
    The ChildrenEnumeration.
    Throws:
    MailException - If an error occurs accessing the Store.

    addChild

    int addChild(java.lang.String path,
                 RmsRecordItem child)
                 throws MailException
    This method add a new child to a Folder.

    Parameters:
    path - The complete path of the Folder.
    child - The RmsRecordItem child to save.
    Returns:
    The new child id
    Throws:
    MailException - If an error occurs accessing the Store.

    updateChild

    void updateChild(java.lang.String path,
                     RmsRecordItem child)
                     throws MailException
    This method updates an existing Folder child in the Store.

    Parameters:
    path - The complete path of the Folder containing the child.
    child - The RmsRecordItem child to save.
    Throws:
    MailException - If an error occurs accessing the Store.

    removeChild

    void removeChild(java.lang.String path,
                     java.lang.String childId)
                     throws MailException
    This method removes a Folder child from the Store.

    Parameters:
    path - The complete path of the Folder containing the child.
    childId - A string representing the unique child ID.
    Throws:
    MailException - If an error occurs accessing the Store.

    countChilds

    int countChilds(java.lang.String path)
                    throws MailException
    This method returns the count of childs in a Folder.

    Parameters:
    path - The complete path of the Folder.
    Throws:
    MailException - If an error occurs accessing the Store.

    countChilds

    int countChilds(java.lang.String path,
                    char prefix)
                    throws MailException
    This method returns the count of childs in a Folder. Only childs with the specified prefix will be counted.

    Parameters:
    path - The complete path of the Folder.
    prefix - The childs type to be counted.
    Throws:
    MailException - If an error occurs accessing the Store.

    setVersion

    void setVersion(int version)
    This method sets the version of the Store which is currently being used on the device. If no version is specified, the Store defaults to the latest one.

    Parameters:
    version - The store version.

    getVersion

    int getVersion()
    This method gets the version of the Store which is currently being used on the device.



    Copyright © 2001-2009 Funambol.