Item API

Access and manipulate evidence items using IItemReader and IItem interfaces

The Item API provides access to evidence items and their properties through two core interfaces:

• IItemReader: Read-only access to item properties and content
• IItem: Full read-write access for processing tasks

IItemReader Interface

The IItemReader interface provides read-only access to evidence items. It is the base interface extended by IItem.

Package: iped.data
Source: iped-api/src/main/java/iped/data/IItemReader.java

Basic Properties

getId() · int

Returns the unique identifier of the item within the case

getName() · String

Returns the filename of the item

getPath() · String

Returns the full path of the item including parent directories

getLength() · Long

Returns the size of the item in bytes

getHash() · String

Returns the hash value of the item (if computed during processing)

Example: Basic Property Access

/api/item-api.mdx:55:72

import iped.data.IItem;
import iped.engine.data.IPEDSource;

File caseDir = new File("/path/to/case");
IPEDSource source = new IPEDSource(caseDir);

// Get item by ID
IItem item = source.getItemByID(12345);

System.out.println("Name: " + item.getName());
System.out.println("Path: " + item.getPath());
System.out.println("Size: " + item.getLength() + " bytes");
System.out.println("Hash: " + item.getHash());
System.out.println("ID: " + item.getId());

source.close();

File Type Information

getExt() · String

Returns the original file extension

getType() · String

Returns the detected file type extension based on signature analysis

getMediaType() · MediaType

Returns the Apache Tika MediaType detected from file signature analysis

getCategorySet() · HashSet<String>

Returns the set of categories assigned to this item

Example: File Type Detection

IItem item = source.getItemByID(12345);

System.out.println("Original Extension: " + item.getExt());
System.out.println("Detected Type: " + item.getType());
System.out.println("Media Type: " + item.getMediaType());
System.out.println("Categories: " + item.getCategorySet());

// Check if item is an image
if (item.getCategorySet().contains("images")) {
    System.out.println("This is an image file");
}

Hierarchical Properties

getParentId() · Integer

Returns the ID of the parent item (null if root level)

getSubitemId() · Integer

Returns the subitem order within its parent, or null if not a subitem

isSubItem() · boolean

Returns true if this is a subitem extracted from a container (e.g., file within a ZIP)

isDir() · boolean

Returns true if the item is a directory

isRoot() · boolean

Returns true if this is a root item

hasChildren() · boolean

Returns true if the item has child items (subitems or carved items)

Example: Navigating Hierarchy

IItem item = source.getItemByID(12345);

if (item.isSubItem()) {
    Integer parentId = item.getParentId();
    IItem parent = source.getItemByID(parentId);
    System.out.println("Parent: " + parent.getName());
}

if (item.hasChildren()) {
    System.out.println("This item contains subitems");
}

State Flags

isDeleted() · boolean

Returns true if the item is a deleted file

isCarved() · boolean

Returns true if the item was recovered through data carving

isTimedOut() · boolean

Returns true if parsing of the item resulted in a timeout

Timestamps

getModDate() · Date

Returns the last modification date of the file

getCreationDate() · Date

Returns the creation date of the file

getAccessDate() · Date

Returns the last access date of the file

getChangeDate() · Date

Returns the change date of the file (filesystem metadata change)

Example: Date Analysis

IItem item = source.getItemByID(12345);

SimpleDateFormat sdf = new SimpleDateFormat("yyyy-MM-dd HH:mm:ss");

Date created = item.getCreationDate();
Date modified = item.getModDate();
Date accessed = item.getAccessDate();

if (created != null) {
    System.out.println("Created: " + sdf.format(created));
}
if (modified != null) {
    System.out.println("Modified: " + sdf.format(modified));
}
if (accessed != null) {
    System.out.println("Accessed: " + sdf.format(accessed));
}

Content Access

getBufferedInputStream() · BufferedInputStream

Returns a buffered input stream to read the item’s raw content. Preferred method for streaming access.

getSeekableInputStream() · SeekableInputStream

Returns a seekable input stream allowing random access to content

getImageInputStream() · ImageInputStream

Returns an ImageInputStream for image processing

getTempFile() · File

Returns a temporary file containing the item’s content. Avoid using if you can work with streams, as this spools data to disk.

getInputStreamFactory() · ISeekableInputStreamFactory

Returns a factory for creating multiple input streams to the same item

Example: Reading Content

import java.io.BufferedInputStream;
import java.io.IOException;
import org.apache.commons.io.IOUtils;

IItem item = source.getItemByID(12345);

// Preferred: Stream content
try (BufferedInputStream is = item.getBufferedInputStream()) {
    byte[] content = IOUtils.toByteArray(is);
    System.out.println("Read " + content.length + " bytes");
}

// For seekable access
try (SeekableInputStream sis = item.getSeekableInputStream()) {
    sis.seek(100);
    byte[] chunk = new byte[50];
    sis.read(chunk);
}

// Avoid: Creates temporary file
File tempFile = item.getTempFile();

Performance: Always prefer streaming methods (getBufferedInputStream(), getSeekableInputStream()) over getTempFile() to avoid unnecessary disk I/O.

Preview and Thumbnails

hasPreview() · boolean

Returns true if a preview/view file exists for this item

getViewFile() · File

Returns the view/preview file path (relative to case), or null if none exists

getPreviewExt() · String

Returns the file extension of the preview file

getThumb() · byte[]

Returns the thumbnail image as a byte array

Metadata

getMetadata() · Metadata

Returns the Apache Tika Metadata object containing all extracted metadata

getExtraAttribute(String key) · Object

Returns the value of a custom extra attribute set by processing modules

getExtraAttributeMap() · Map<String, Object>

Returns the map of all extra attributes

Example: Accessing Metadata

import org.apache.tika.metadata.Metadata;

IItem item = source.getItemByID(12345);

Metadata metadata = item.getMetadata();

// Access standard metadata
String author = metadata.get("Author");
String title = metadata.get("title");

System.out.println("Author: " + author);
System.out.println("Title: " + title);

// Access extra attributes set by custom tasks
Object customAttr = item.getExtraAttribute("customProperty");
if (customAttr != null) {
    System.out.println("Custom: " + customAttr);
}

Data Source

getDataSource() · IDataSource

Returns the data source (evidence) that contains this item

getIdInDataSource() · String

Returns the identifier of this item within its original data source

IItem Interface

The IItem interface extends IItemReader with write operations for use in processing tasks.

Package: iped.data
Source: iped-api/src/main/java/iped/data/IItem.java

Modifying Properties

setName(String name) · void

Sets the filename

setExtension(String ext) · void

Sets the file extension

setMediaType(MediaType mediaType) · void

Sets the detected media type

setLength(Long length) · void

Sets the file size in bytes

setHash(String hash) · void

Sets the hash value

Category Management

addCategory(String category) · void

Adds the item to a category

removeCategory(String category) · void

Removes the item from a category

setCategory(String category) · void

Replaces all categories with a single category

Example: Category Management

IItem item = source.getItemByID(12345);

// Add to categories
item.addCategory("suspicious");
item.addCategory("encrypted");

// Check categories
if (item.getCategorySet().contains("encrypted")) {
    System.out.println("Item is encrypted");
}

// Remove category
item.removeCategory("encrypted");

State Management

setDeleted(boolean deleted) · void

Marks the item as deleted

setCarved(boolean carved) · void

Marks the item as recovered through carving

setToIgnore(boolean toIgnore) · void

Marks the item to be ignored by subsequent processing tasks and excluded from the case

setAddToCase(boolean addToCase) · void

Sets whether the item should be added to the final case

setToExtract(boolean toExtract) · void

Sets whether the item should be extracted/exported

Extra Attributes

setExtraAttribute(String key, Object value) · void

Sets a custom extra attribute that will be indexed and searchable

setTempAttribute(String key, Object value) · void

Sets a temporary attribute (not indexed, used only during processing)

Example: Custom Attributes in Task

public class CustomAnalysisTask extends AbstractTask {
    @Override
    protected void process(IItem item) throws Exception {
        // Analyze content
        double suspicionScore = analyzeContent(item);
        
        // Store result as extra attribute
        item.setExtraAttribute("suspicionScore", suspicionScore);
        
        // Add to category if suspicious
        if (suspicionScore > 0.8) {
            item.addCategory("high-risk");
        }
        
        // Temporary processing state (not indexed)
        item.setTempAttribute("processingTimestamp", System.currentTimeMillis());
    }
}

Resource Management

dispose() · void

Releases resources used by the item, including temporary files and file handles. Important: Always call when done processing.

createChildItem() · IItem

Creates a new child item (subitem) of this item. Used when extracting embedded content.

Example: Creating Subitems

public class ContainerExpansionTask extends AbstractTask {
    @Override
    protected void process(IItem item) throws Exception {
        if (isContainer(item)) {
            List<ExtractedFile> files = extractFiles(item);
            
            for (ExtractedFile file : files) {
                // Create child item
                IItem subitem = item.createChildItem();
                subitem.setName(file.getName());
                subitem.setLength(file.getSize());
                subitem.setSubItem(true);
                subitem.setParentId(item.getId());
                
                // Set content factory
                subitem.setInputStreamFactory(
                    new ByteArrayInputStreamFactory(file.getContent())
                );
                
                // Process subitem through pipeline
                worker.processNewItem(subitem);
            }
            
            item.setHasChildren(true);
        }
    }
}

IIPEDSource Interface

The IIPEDSource interface provides access to IPED cases and their indices.

Package: iped.data
Source: iped-api/src/main/java/iped/data/IIPEDSource.java

Opening Cases

IPEDSource(File casePath) · constructor

Opens an IPED case from the specified directory

Retrieving Items

getItemByID(int id) · IItem

Returns the item with the specified ID

getItemByLuceneID(int docID) · IItem

Returns the item with the specified Lucene document ID

getLuceneId(int id) · int

Converts item ID to Lucene document ID

getId(int luceneId) · int

Converts Lucene document ID to item ID

Case Information

getCaseDir() · File

Returns the case directory

getModuleDir() · File

Returns the IPED module directory (containing index, data, etc.)

getTotalItems() · int

Returns the total number of items in the case

getLastId() · int

Returns the highest item ID in the case

Index Access

getReader() · IndexReader

Returns the Lucene IndexReader for low-level index access

getSearcher() · IndexSearcher

Returns the Lucene IndexSearcher for executing queries

getAnalyzer() · Analyzer

Returns the Lucene Analyzer used for text analysis

Categories and Metadata

getLeafCategories() · List<String>

Returns the list of leaf-level categories in the case

getExtraAttributes() · Set<String>

Returns the set of extra attribute names defined in the case

getKeywords() · Set<String>

Returns the set of keywords/search terms saved in the case

Example: Case Statistics

import iped.engine.data.IPEDSource;

File caseDir = new File("/path/to/case");
IPEDSource source = new IPEDSource(caseDir);

System.out.println("Case: " + source.getCaseDir().getName());
System.out.println("Total Items: " + source.getTotalItems());
System.out.println("Highest ID: " + source.getLastId());
System.out.println("Categories: " + source.getLeafCategories());
System.out.println("Extra Attributes: " + source.getExtraAttributes());

source.close();

Best Practices

Always Close Resources: Use try-with-resources or explicitly call close() on IPEDSource and dispose() on IItem instances.

Thread Safety: IItem objects are not thread-safe. Each processing worker maintains its own item instances.

Stream Content: Prefer streaming methods over getTempFile() to avoid unnecessary disk I/O and improve performance.

See Also

• Search API - Query and filter items
• Task API - Build custom processing tasks
• Web API - Remote item access via REST