Package org.apache.tika.server.core.resource

Class UnpackerResource

java.lang.Object

org.apache.tika.server.core.resource.UnpackerResource

@Path("/unpack")
public class UnpackerResource
extends Object

JAX-RS resource for unpacking embedded documents from container files.

This endpoint uses process-isolated parsing via tika-pipes with ParseMode.UNPACK. Embedded documents are extracted and returned as a zip archive.

Endpoints:

• PUT /unpack - Extract embedded documents (raw body)
• POST /unpack - Extract with config (multipart: file + optional JSON config)
• PUT /unpack/all - Extract embedded + container text/metadata
• POST /unpack/all - Extract all with config (multipart)

Configuration:

None required. The server wires up its own __-prefixed fetcher and emitter against temp directories it owns, confined by basePath. Those ids are reserved and a request that names one is rejected.

Multipart Configuration (POST endpoints):

Submit as multipart/form-data with:

• "file" part: the document to unpack
• "config" part (optional): JSON configuration

Example config JSON:

 {
   "parse-context": {
     "unpack-config": {
       "suffixStrategy": "DETECTED",
       "includeOriginal": true
     },
     "standard-unpack-selector": {
       "includeMimeTypes": ["image/jpeg", "image/png"],
       "excludeMimeTypes": ["application/pdf"]
     },
     "embedded-limits": {
       "maxDepth": 5,
       "maxCount": 100
     }
   }
 }
 

Frictionless Data Package Format:

To receive output in Frictionless Data Package format (with datapackage.json manifest, SHA256 hashes, and files in unpacked/ subdirectory), use:

 {
   "parse-context": {
     "unpack-config": {
       "outputFormat": "FRICTIONLESS",
       "outputMode": "ZIPPED",
       "includeMetadata": true
     }
   }
 }
 

The Frictionless zip structure:

 output.zip
 ├── datapackage.json      # Manifest with file list, SHA256 hashes, mimetypes
 ├── metadata.json         # Full RMETA metadata (unless includeMetadata=false)
 └── unpacked/
     ├── 00000001.pdf
     ├── 00000002.png
     └── ...
 

Breaking Changes from Pre-4.0:

• Parsing now runs in a separate process for memory safety
• Configuration via HTTP headers is no longer supported; use multipart JSON config
• Custom EmbeddedDocumentExtractor in ParseContext is ignored; use UnpackSelector
• The unpackMaxBytes header is removed; use embedded-limits in config

Constructor Summary

Constructors

Constructor	Description
UnpackerResource(TikaResource tikaResource)

Method Summary

Modifier and Type	Method	Description
jakarta.ws.rs.core.Response	unpack(InputStream is, jakarta.ws.rs.core.HttpHeaders httpHeaders)	Extracts embedded documents from a container file (simple PUT, no config).
jakarta.ws.rs.core.Response	unpackAll(InputStream is, jakarta.ws.rs.core.HttpHeaders httpHeaders)	Extracts embedded documents plus original document and metadata (simple PUT).
jakarta.ws.rs.core.Response	unpackAll(InputStream is, jakarta.ws.rs.core.HttpHeaders httpHeaders, String handlerTypeName)	As /unpack/all, with the handler for the metadata's tk:content in the path.
jakarta.ws.rs.core.Response	unpackAllConfig(List<org.apache.cxf.jaxrs.ext.multipart.Attachment> attachments, jakarta.ws.rs.core.HttpHeaders httpHeaders)	The config-variant spelling, POST /unpack/all/config: the same as POST /unpack/all. 4.0 accepted it by accident (the wildcard route swallowed the segment) and documented it; kept so it does not turn into a handler named "config".
jakarta.ws.rs.core.Response	unpackAllConfig(List<org.apache.cxf.jaxrs.ext.multipart.Attachment> attachments, jakarta.ws.rs.core.HttpHeaders httpHeaders, String handlerTypeName)	As POST /unpack/all/config, with the sidecar handler named in the path, like /rmeta/config/{handlerType}.
jakarta.ws.rs.core.Response	unpackAllWithConfig(List<org.apache.cxf.jaxrs.ext.multipart.Attachment> attachments, jakarta.ws.rs.core.HttpHeaders httpHeaders)	Extracts embedded documents plus original/metadata with config (multipart POST).
jakarta.ws.rs.core.Response	unpackAllWithConfig(List<org.apache.cxf.jaxrs.ext.multipart.Attachment> attachments, jakarta.ws.rs.core.HttpHeaders httpHeaders, String handlerTypeName)	As POST /unpack/all, with the sidecar handler named in the path.
jakarta.ws.rs.core.Response	unpackAllWithPreset(InputStream is, jakarta.ws.rs.core.HttpHeaders httpHeaders, String presetName)	As /unpack/all, with the named preset's parse-context fragment applied.
jakarta.ws.rs.core.Response	unpackWithConfig(List<org.apache.cxf.jaxrs.ext.multipart.Attachment> attachments, jakarta.ws.rs.core.HttpHeaders httpHeaders)	Extracts embedded documents with configuration (multipart POST).
jakarta.ws.rs.core.Response	unpackWithPreset(InputStream is, jakarta.ws.rs.core.HttpHeaders httpHeaders, String presetName)	As /unpack, with the named preset's parse-context fragment applied.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

UnpackerResource

public UnpackerResource(TikaResource tikaResource)

Method Details

unpack

@Path("")
@PUT
@Produces("application/zip")
public jakarta.ws.rs.core.Response unpack(InputStream is,
 @Context
 jakarta.ws.rs.core.HttpHeaders httpHeaders)
                                   throws Exception

Extracts embedded documents from a container file (simple PUT, no config). Returns a zip archive containing the extracted files.

Parameters:

is - input stream containing the document

httpHeaders - HTTP headers

info - URI info

Returns:

streaming zip response

Throws:

Exception

unpackWithConfig

@Path("")
@POST
@Consumes("multipart/form-data")
@Produces("application/zip")
public jakarta.ws.rs.core.Response unpackWithConfig(List<org.apache.cxf.jaxrs.ext.multipart.Attachment> attachments,
 @Context
 jakarta.ws.rs.core.HttpHeaders httpHeaders)
                                             throws Exception

Extracts embedded documents with configuration (multipart POST). Accepts multipart/form-data with "file" and optional "config" parts.

Parameters:

attachments - multipart attachments

httpHeaders - HTTP headers

info - URI info

Returns:

streaming zip response

Throws:

Exception

unpackAll

@Path("/all")
@PUT
@Produces("application/zip")
public jakarta.ws.rs.core.Response unpackAll(InputStream is,
 @Context
 jakarta.ws.rs.core.HttpHeaders httpHeaders)
                                      throws Exception

Extracts embedded documents plus original document and metadata (simple PUT). Returns a zip archive containing extracted files, original document, and metadata.

Parameters:

is - input stream containing the document

httpHeaders - HTTP headers

info - URI info

Returns:

streaming zip response

Throws:

Exception

unpackAll

@Path("/all/{handler}")
@PUT
@Produces("application/zip")
public jakarta.ws.rs.core.Response unpackAll(InputStream is,
 @Context
 jakarta.ws.rs.core.HttpHeaders httpHeaders,
 @PathParam("handler")
 String handlerTypeName)
                                      throws Exception

As /unpack/all, with the handler for the metadata's tk:content in the path.

Throws:

Exception

unpackAllWithConfig

@Path("/all")
@POST
@Consumes("multipart/form-data")
@Produces("application/zip")
public jakarta.ws.rs.core.Response unpackAllWithConfig(List<org.apache.cxf.jaxrs.ext.multipart.Attachment> attachments,
 @Context
 jakarta.ws.rs.core.HttpHeaders httpHeaders)
                                                throws Exception

Extracts embedded documents plus original/metadata with config (multipart POST). Accepts multipart/form-data with "file" and optional "config" parts.

Parameters:

attachments - multipart attachments

httpHeaders - HTTP headers

info - URI info

Returns:

streaming zip response

Throws:

Exception

unpackAllConfig

@Path("/all/config")
@POST
@Consumes("multipart/form-data")
@Produces("application/zip")
public jakarta.ws.rs.core.Response unpackAllConfig(List<org.apache.cxf.jaxrs.ext.multipart.Attachment> attachments,
 @Context
 jakarta.ws.rs.core.HttpHeaders httpHeaders)
                                            throws Exception

The config-variant spelling, POST /unpack/all/config: the same as POST /unpack/all. 4.0 accepted it by accident (the wildcard route swallowed the segment) and documented it; kept so it does not turn into a handler named "config".

Throws:

Exception

unpackAllConfig

@Path("/all/config/{handler}")
@POST
@Consumes("multipart/form-data")
@Produces("application/zip")
public jakarta.ws.rs.core.Response unpackAllConfig(List<org.apache.cxf.jaxrs.ext.multipart.Attachment> attachments,
 @Context
 jakarta.ws.rs.core.HttpHeaders httpHeaders,
 @PathParam("handler")
 String handlerTypeName)
                                            throws Exception

As POST /unpack/all/config, with the sidecar handler named in the path, like /rmeta/config/{handlerType}.

Throws:

Exception

unpackAllWithConfig

@Path("/all/{handler}")
@POST
@Consumes("multipart/form-data")
@Produces("application/zip")
public jakarta.ws.rs.core.Response unpackAllWithConfig(List<org.apache.cxf.jaxrs.ext.multipart.Attachment> attachments,
 @Context
 jakarta.ws.rs.core.HttpHeaders httpHeaders,
 @PathParam("handler")
 String handlerTypeName)
                                                throws Exception

As POST /unpack/all, with the sidecar handler named in the path.

Throws:

Exception

unpackWithPreset

@Path("/preset/{presetName}")
@PUT
@Produces("application/zip")
public jakarta.ws.rs.core.Response unpackWithPreset(InputStream is,
 @Context
 jakarta.ws.rs.core.HttpHeaders httpHeaders,
 @PathParam("presetName")
 String presetName)
                                             throws Exception

As /unpack, with the named preset's parse-context fragment applied. Takes no config part -- a preset never combines with request configuration.

Throws:

Exception

unpackAllWithPreset

@Path("/preset/{presetName}/all")
@PUT
@Produces("application/zip")
public jakarta.ws.rs.core.Response unpackAllWithPreset(InputStream is,
 @Context
 jakarta.ws.rs.core.HttpHeaders httpHeaders,
 @PathParam("presetName")
 String presetName)
                                                throws Exception

As /unpack/all, with the named preset's parse-context fragment applied.

Throws:

Exception