> ## Documentation Index > Fetch the complete documentation index at: https://mintlify.com/sepinf-inc/IPED/llms.txt > Use this file to discover all available pages before exploring further. # 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 Returns the unique identifier of the item within the case Returns the filename of the item Returns the full path of the item including parent directories Returns the size of the item in bytes Returns the hash value of the item (if computed during processing) ### Example: Basic Property Access ```java /api/item-api.mdx:55:72 theme={null} 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 Returns the original file extension Returns the detected file type extension based on signature analysis Returns the Apache Tika MediaType detected from file signature analysis Returns the set of categories assigned to this item ### Example: File Type Detection ```java theme={null} 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 Returns the ID of the parent item (null if root level) Returns the subitem order within its parent, or null if not a subitem Returns true if this is a subitem extracted from a container (e.g., file within a ZIP) Returns true if the item is a directory Returns true if this is a root item Returns true if the item has child items (subitems or carved items) ### Example: Navigating Hierarchy ```java theme={null} 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 Returns true if the item is a deleted file Returns true if the item was recovered through data carving Returns true if parsing of the item resulted in a timeout ### Timestamps Returns the last modification date of the file Returns the creation date of the file Returns the last access date of the file Returns the change date of the file (filesystem metadata change) ### Example: Date Analysis ```java theme={null} 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 Returns a buffered input stream to read the item's raw content. **Preferred method** for streaming access. Returns a seekable input stream allowing random access to content Returns an ImageInputStream for image processing Returns a temporary file containing the item's content. **Avoid using** if you can work with streams, as this spools data to disk. Returns a factory for creating multiple input streams to the same item ### Example: Reading Content ```java theme={null} 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 Returns true if a preview/view file exists for this item Returns the view/preview file path (relative to case), or null if none exists Returns the file extension of the preview file Returns the thumbnail image as a byte array ### Metadata Returns the Apache Tika Metadata object containing all extracted metadata Returns the value of a custom extra attribute set by processing modules Returns the map of all extra attributes ### Example: Accessing Metadata ```java theme={null} 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 Returns the data source (evidence) that contains this item 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 Sets the filename Sets the file extension Sets the detected media type Sets the file size in bytes Sets the hash value ### Category Management Adds the item to a category Removes the item from a category Replaces all categories with a single category ### Example: Category Management ```java theme={null} 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 Marks the item as deleted Marks the item as recovered through carving Marks the item to be ignored by subsequent processing tasks and excluded from the case Sets whether the item should be added to the final case Sets whether the item should be extracted/exported ### Extra Attributes Sets a custom extra attribute that will be indexed and searchable Sets a temporary attribute (not indexed, used only during processing) ### Example: Custom Attributes in Task ```java theme={null} 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 Releases resources used by the item, including temporary files and file handles. **Important**: Always call when done processing. Creates a new child item (subitem) of this item. Used when extracting embedded content. ### Example: Creating Subitems ```java theme={null} public class ContainerExpansionTask extends AbstractTask { @Override protected void process(IItem item) throws Exception { if (isContainer(item)) { List 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 Opens an IPED case from the specified directory ### Retrieving Items Returns the item with the specified ID Returns the item with the specified Lucene document ID Converts item ID to Lucene document ID Converts Lucene document ID to item ID ### Case Information Returns the case directory Returns the IPED module directory (containing index, data, etc.) Returns the total number of items in the case Returns the highest item ID in the case ### Index Access Returns the Lucene IndexReader for low-level index access Returns the Lucene IndexSearcher for executing queries Returns the Lucene Analyzer used for text analysis ### Categories and Metadata Returns the list of leaf-level categories in the case Returns the set of extra attribute names defined in the case Returns the set of keywords/search terms saved in the case ### Example: Case Statistics ```java theme={null} 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](/api/search-api) - Query and filter items * [Task API](/api/task-api) - Build custom processing tasks * [Web API](/api/web/endpoints) - Remote item access via REST This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.