mahuta_java_api.md

Mahuta Java API

Configuration

Before starting, the client needs to instantiate a Mahuta object:

Mahuta mahuta = new MahutaFactory()
    .configureStorage(IPFSService.connect("localhost", 5001).configureThreadPool(2))
    .configureIndexer(ElasticSearchService.connect("localhost", 9300, "cluster-name").withIndex("article"))
    .defaultImplementation();

Storage configureStorage

Storage represents the storage layer (aka IPFS)

StorageService storage = IPFSService.connect(host, port) or .connect(multiaddress)
    .configureTimeout(timeout) 
    .configureRetry(maxRetry, delay) 
    .addReplica(pinningService)

property	type	optional	default	description
connect(host, port)	String, Integer	false	localhost, 5001	connect to the IPFS node via it HTTP address host:port
connect(multiaddress)	String	false		connect to the IPFS node via its multiaddress
configureTimeout(timeout)	Integer	true	5000	Configure timeout (in milliseconds)
configureRetry(maxRetry, delay)	Integer, Duration	true	3, 0 (sec)	Configure retry on error with delay between each retry attempt
addReplica(pinningService)	PinningService	true		Add Replica service. files are pinned on the connection node (connect)and on each replica service (can be another IPFS node or a IPFS-cluster node

Indexer configureIndexer

Indexer represents the indexing layer (ElasticSearch)

IndexerService indexer = ElasticSearchService.connect(host, port, clusterName)
    .configureIndexNullValue(indexNullValue)
    .withIndex(indexName) or withIndex(indexName, configuration) 

property	type	optional	default	description
connect(host, port, clusterName)	String, Integer, String	false	localhost, 9200, null	connect to ElasticSearch
configureIndexNullValue(indexNullValue)	Boolean	true	false	Configure Index null value (null
withIndex(indexName)	String	true		Create an index during the connection
withIndex(indexName, configuration)	String, InputStream	true		Create an index during the connection with configuration

Service implementation

Select the service implementation to use:

• DefaultMahutaService: Default implementation (synchronous functions)

    .defaultImplementation()

• AsynchonousPinningMahutaService: Implementation with asynchronous pinning

    .asynchronousPinningImplementation(long schedulerPeriod)

Operations

Create Index

Create an index

CreateIndexResponse response = mahuta.prepareCreateIndex(indexName)
    .configuration(configuration)
    .execute();

property	type	optional	default	description
indexName	String	false		Index name
configuration	InputStream	true		Configuration file (on ElasticSearch index mapping JSON)

Get Indexes

Retrieve all indexed from the indexer

GetIndexesResponse response = mahuta.prepareGetIndexes()
    .execute();

property	type	optional	default	description

Index (String)

Index a String document

IndexingResponse response = mahuta.prepareStringIndexing(indexName, content)
    .indexDocId(indexDocId) 
    .contentType(contentType) 
    .indexFields(indexFields) 
    .indexContent(indexContent) 
    .execute();

property	type	optional	default	description
indexName, content	String, String	false		Index name and content
indexDocId	String	true		Document ID to index the document against (if null, autogenerated ID)
contentType	String	true		Mimetype (if null, content type guessing function)
indexFields	Map<String, Object>	true		Index field
indexContent	Boolean	true	false	Store content in the indexer (caching) - Converted into Base64

Index (CID)

Index a document already on IPFS by its CID

IndexingResponse response = mahuta.prepareCIDndexing(indexName, cid)
    .indexDocId(indexDocId) 
    .contentType(contentType) 
    .indexFields(indexFields) 
    .indexContent(indexContent) 
    .execute();

property	type	optional	default	description
indexName, cid	String, String	false		Index name and cid
indexDocId	String	true		Document ID to index the document against (if null, autogenerated ID)
contentType	String	true		Mimetype (if null, content type guessing function)
indexFields	Map<String, Object>	true		Index field
indexContent	Boolean	true	false	Store content in the indexer (caching) - Converted into Base64

Index (InputStream)

Index any type of content

IndexingResponse response = mahuta.prepareInputStreamIndexing(indexName, content)
    .indexDocId(indexDocId) 
    .contentType(contentType) 
    .indexFields(indexFields) 
    .indexContent(indexContent) 
    .execute();

property	type	optional	default	description
indexName, content	String, InputStream	false		Index name and content
indexDocId	String	true		ID to identify the the content in the index (if null, autogenerated ID)
contentType	String	true		Mimetype (if null, content type guessing function)
indexFields	Map<String, Object>	true		Index field
indexContent	Boolean	true	false	Store content in the indexer (caching) - Converted into Base64

Deindexing

Remove a document from the index and unpin

DeindexingResponse response = mahuta.prepareDeindexing(indexName, indexDocIn)
    .execute();

property	type	optional	default	description
indexName	String	false		Index name
indexDocId	String	false		ID identifying the file to unindex and unpin

Update field

Update a field in the index without touching the file

UpdateFieldResponse response = mahuta.prepareUpdateField(String indexName, String indexDocId, String key, Object value)
    .execute();

property	type	optional	default	description
indexName	String	false		Index name
indexDocId	String	false		Document ID identifying the file
key	String	false		Index Field name
value	Object	false		New value (nullable)

Get

Retrieve a file by its IndexDocId or ContentsID (IPFS hash)

GetResponse response = mahuta.prepareGet()
    .indexName(index)
    .indexDocId(index) or .contentId(index)
    .loadFile(index)
    .execute();

property	type	optional	default	description
indexName	String	false		Index name
indexDocId	String	true		Document ID identifying the file
contentId	String	true		Content ID (IPFS hash)
loadFile	Boolean	true	false	Load Metadata only (index fields) or Metadata and file

Search

Search content indexed by query

SearchResponse response = mahuta.prepareSearch()
    .indexName(indexName)
    .query(query)
    .loadFile(index)
    .execute();

property	type	optional	default	description
indexName	String	false		Index name
query	Query	false		Query
loadFile	Boolean	false	false	Load Metadata only (index fields) or Metadata and file