http://poi.apache.org/: Apache POI - Java API To Access Microsoft Format Files (Apache Software Foundation) 

/* ====================================================================
   Licensed to the Apache Software Foundation (ASF) under one or more
   contributor license agreements.  See the NOTICE file distributed with
   this work for additional information regarding copyright ownership.
   The ASF licenses this file to You under the Apache License, Version 2.0
   (the "License"); you may not use this file except in compliance with
   the License.  You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.
==================================================================== */


package org.apache.poi.poifs.filesystem;

import java.io.FileNotFoundException;
import java.io.IOException;
import java.io.InputStream;
import java.util.Iterator;
import java.util.Set;

import org.apache.poi.hpsf.ClassID;


This interface defines methods specific to Directory objects
managed by a Filesystem instance.

Author:Marc Johnson (mjohnson at apache dot org)
/**
 * This interface defines methods specific to Directory objects
 * managed by a Filesystem instance.
 *
 * @author Marc Johnson (mjohnson at apache dot org)
 */

public interface DirectoryEntry
    extends Entry, Iterable<Entry>
{

    
get an iterator of the Entry instances contained directly in
this instance (in other words, children only; no grandchildren
etc.)

Returns:iterator; never null, but hasNext() may return false
        immediately (i.e., this DirectoryEntry is empty). All
        objects retrieved by next() are guaranteed to be
        implementations of Entry.
/**
     * get an iterator of the Entry instances contained directly in
     * this instance (in other words, children only; no grandchildren
     * etc.)
     *
     * @return iterator; never null, but hasNext() may return false
     *         immediately (i.e., this DirectoryEntry is empty). All
     *         objects retrieved by next() are guaranteed to be
     *         implementations of Entry.
     */

    public Iterator<Entry> getEntries();
    
    
get the names of all the Entries contained directly in this
instance (in other words, names of children only; no grandchildren
etc).

Returns:the names of all the entries that may be retrieved with
        getEntry(String), which may be empty (if this 
        DirectoryEntry is empty)
/**
     * get the names of all the Entries contained directly in this
     * instance (in other words, names of children only; no grandchildren
     * etc).
     *
     * @return the names of all the entries that may be retrieved with
     *         getEntry(String), which may be empty (if this 
     *         DirectoryEntry is empty)
     */
    public Set<String> getEntryNames();

    
is this DirectoryEntry empty?

Returns:true if this instance contains no Entry instances
/**
     * is this DirectoryEntry empty?
     *
     * @return true if this instance contains no Entry instances
     */

    public boolean isEmpty();

    
find out how many Entry instances are contained directly within
this DirectoryEntry

Returns:number of immediately (no grandchildren etc.) contained
        Entry instances
/**
     * find out how many Entry instances are contained directly within
     * this DirectoryEntry
     *
     * @return number of immediately (no grandchildren etc.) contained
     *         Entry instances
     */

    public int getEntryCount();

    
Checks if entry with specified name present

/**
     * Checks if entry with specified name present
     */

    public boolean hasEntry( final String name );

    
get a specified Entry by name

Params:
  • name – the name of the Entry to obtain.
Throws:
Returns:the specified Entry, if it is directly contained in
        this DirectoryEntry
/**
     * get a specified Entry by name
     *
     * @param name the name of the Entry to obtain.
     *
     * @return the specified Entry, if it is directly contained in
     *         this DirectoryEntry
     *
     * @exception FileNotFoundException if no Entry with the specified
     *            name exists in this DirectoryEntry
     */

    public Entry getEntry(final String name)
        throws FileNotFoundException;

    
create a new DocumentEntry

Params:
  • name – the name of the new DocumentEntry
  • stream – the InputStream from which to create the new
              DocumentEntry
Throws:
Returns:the new DocumentEntry
/**
     * create a new DocumentEntry
     *
     * @param name the name of the new DocumentEntry
     * @param stream the InputStream from which to create the new
     *               DocumentEntry
     *
     * @return the new DocumentEntry
     *
     * @exception IOException
     */

    public DocumentEntry createDocument(final String name,
                                        final InputStream stream)
        throws IOException;

    
create a new DocumentEntry; the data will be provided later

Params:
  • name – the name of the new DocumentEntry
  • size – the size of the new DocumentEntry
  • writer – the writer of the new DocumentEntry
Throws:
Returns:the new DocumentEntry
/**
     * create a new DocumentEntry; the data will be provided later
     *
     * @param name the name of the new DocumentEntry
     * @param size the size of the new DocumentEntry
     * @param writer the writer of the new DocumentEntry
     *
     * @return the new DocumentEntry
     *
     * @exception IOException
     */

    public DocumentEntry createDocument(final String name, final int size,
                                        final POIFSWriterListener writer)
        throws IOException;

    
create a new DirectoryEntry

Params:
  • name – the name of the new DirectoryEntry
Throws:
Returns:the new DirectoryEntry
/**
     * create a new DirectoryEntry
     *
     * @param name the name of the new DirectoryEntry
     *
     * @return the new DirectoryEntry
     *
     * @exception IOException
     */

    public DirectoryEntry createDirectory(final String name)
        throws IOException;

    
Gets the storage clsid of the directory entry

Returns:storage Class ID
/**
     * Gets the storage clsid of the directory entry
     *
     * @return storage Class ID
     */
    public ClassID getStorageClsid();

    
Sets the storage clsid for the directory entry

Params:
  • clsidStorage – storage Class ID
/**
     * Sets the storage clsid for the directory entry
     *
     * @param clsidStorage storage Class ID
     */
    public void setStorageClsid(ClassID clsidStorage);

}   // end public interface DirectoryEntry