Item API

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.

Core API

Web API

IItemReader Interface

Basic Properties

Example: Basic Property Access

File Type Information

Example: File Type Detection

Hierarchical Properties

Example: Navigating Hierarchy

State Flags

Timestamps

Example: Date Analysis

Content Access

Example: Reading Content

Preview and Thumbnails

Metadata

Example: Accessing Metadata

Data Source

IItem Interface

Modifying Properties

Category Management

Example: Category Management

State Management

Extra Attributes

Example: Custom Attributes in Task

Resource Management

Example: Creating Subitems

IIPEDSource Interface

Opening Cases

Retrieving Items

Case Information

Index Access

Categories and Metadata

Example: Case Statistics

Best Practices

See Also

Build docs developers (and LLMs) love

Core API

Web API

​IItemReader Interface

​Basic Properties

​Example: Basic Property Access

​File Type Information

​Example: File Type Detection

​Hierarchical Properties

​Example: Navigating Hierarchy

​State Flags

​Timestamps

​Example: Date Analysis

​Content Access

​Example: Reading Content

​Preview and Thumbnails

​Metadata

​Example: Accessing Metadata

​Data Source

​IItem Interface

​Modifying Properties

​Category Management

​Example: Category Management

​State Management

​Extra Attributes

​Example: Custom Attributes in Task

​Resource Management

​Example: Creating Subitems

​IIPEDSource Interface

​Opening Cases

​Retrieving Items

​Case Information

​Index Access

​Categories and Metadata

​Example: Case Statistics

​Best Practices

​See Also

Build docs developers (and LLMs) love

IItemReader Interface

Basic Properties

Example: Basic Property Access

File Type Information

Example: File Type Detection

Hierarchical Properties

Example: Navigating Hierarchy

State Flags

Timestamps

Example: Date Analysis

Content Access

Example: Reading Content

Preview and Thumbnails

Metadata

Example: Accessing Metadata

Data Source

IItem Interface

Modifying Properties

Category Management

Example: Category Management

State Management

Extra Attributes

Example: Custom Attributes in Task

Resource Management

Example: Creating Subitems

IIPEDSource Interface

Opening Cases

Retrieving Items

Case Information

Index Access

Categories and Metadata

Example: Case Statistics

Best Practices

See Also