/**
* Searches for documents and concepts by using partial matches on the label(s) fields.
*
* @param parameters The parameters to be used in the service call, account_id, corpus and query
* are required.
* <ul>
* <li>String account_id - The account identifier.<br>
* <li>String corpus - The corpus name.<br>
* <li>RequestedFields concept_fields - Additional fields to be included in the concept
* objects.<br>
* <li>RequestedFields document_fields - Additional fields to be included in the document
* objects.<br>
* <li>Boolean concepts - Whether to return concepts that have a label match.<br>
* <li>String query - The query string.<br>
* <li>Boolean prefix - Whether the query string should be treated as a prefix.<br>
* <li>Integer limit - The maximum number of concepts to be returned.<br>
* </ul>
*
* @return {@link Matches}
*/
public Matches searchCorpusByLabel(Map<String, Object> parameters) {
Validate.notNull(parameters.get(ACCOUNT_ID), "account_id can't be null");
Validate.notNull(parameters.get(CORPUS), "corpus can't be null");
Validate.notNull(parameters.get(QUERY), "query can't be null");
String corpusId =
createCorpusIdPath((String) parameters.get(ACCOUNT_ID), (String) parameters.get(CORPUS));
Map<String, Object> queryParameters = new HashMap<String, Object>();
String[] queryParams = new String[] {QUERY, PREFIX, LIMIT, CONCEPTS};
for (String param : queryParams) {
if (parameters.containsKey(param)) queryParameters.put(param, parameters.get(param));
}
if (parameters.get(CONCEPT_FIELDS) != null) {
RequestedFields fields = (RequestedFields) parameters.get(CONCEPT_FIELDS);
if (fields != null && fields.getFields() != null && !fields.getFields().isEmpty())
queryParameters.put(CONCEPT_FIELDS, fields.toString());
}
if (parameters.get(DOCUMENT_FIELDS) != null) {
RequestedFields fields = (RequestedFields) parameters.get(DOCUMENT_FIELDS);
if (fields != null && fields.getFields() != null && !fields.getFields().isEmpty())
queryParameters.put(DOCUMENT_FIELDS, fields.toString());
}
return executeRequest(corpusId + LABEL_SEARCH_PATH, queryParameters, Matches.class);
}
/**
* Performs a conceptual search within a corpus.
*
* @param parameters The parameters to be used in the service call, account_id, corpus and ids are
* required.
* <ul>
* <li>String account_id - The account identifier.<br>
* <li>String corpus - The corpus name.<br>
* <li>RequestedFields concept_fields - Additional fields to be included in the concept
* objects.<br>
* <li>RequestedFields document_fields - Additional fields to be included in the document
* objects.<br>
* <li>String ids - JSON array of concept and/or document ids.<br>
* <li>Integer cursor - A number of items to skip.<br>
* <li>Integer limit - The maximum number of concepts to be returned.<br>
* </ul>
*
* @return {@link QueryConcepts}
*/
public QueryConcepts conceptualSearch(Map<String, Object> parameters) {
Validate.notNull(parameters.get(ACCOUNT_ID), "account_id can't be null");
Validate.notNull(parameters.get(CORPUS), "corpus can't be null");
Validate.notNull(parameters.get(IDS), "ids can't be null");
String corpusId =
createCorpusIdPath((String) parameters.get(ACCOUNT_ID), (String) parameters.get(CORPUS));
Map<String, Object> queryParams = new HashMap<String, Object>();
String[] queryParameters = new String[] {CURSOR, LIMIT};
for (String param : queryParameters) {
if (parameters.containsKey(param)) queryParams.put(param, parameters.get(param));
}
JsonArray IdsJsonArray = new JsonArray();
@SuppressWarnings("unchecked")
List<String> ids = (List<String>) parameters.get(IDS);
for (String value : ids) {
IdsJsonArray.add(new JsonPrimitive(value));
}
queryParams.put(IDS, IdsJsonArray.toString());
if (parameters.get(CONCEPT_FIELDS) != null) {
RequestedFields fields = (RequestedFields) parameters.get(CONCEPT_FIELDS);
if (fields != null && fields.getFields() != null && !fields.getFields().isEmpty())
queryParams.put(CONCEPT_FIELDS, fields.toString());
}
if (parameters.get(DOCUMENT_FIELDS) != null) {
RequestedFields fields = (RequestedFields) parameters.get(DOCUMENT_FIELDS);
if (fields != null && fields.getFields() != null && !fields.getFields().isEmpty())
queryParams.put(DOCUMENT_FIELDS, fields.toString());
}
return executeRequest(corpusId + CONCEPTUAL_SEARCH_PATH, queryParams, QueryConcepts.class);
}
/**
* Retrieves concepts that are related to an entire corpus.
*
* @param parameters The parameters to be used in the service call, account_id, corpus and
* concepts are required.
* <ul>
* <li>String account_id - The account identifier.<br>
* <li>String corpus - The corpus name.<br>
* <li>RequestedFields concept_fields - Additional fields to be included in the concept
* objects.<br>
* <li>Integer level - A number in the range 0 - 3 that represents the level of popularity
* of related concepts.<br>
* <li>Integer limit - The maximum number of concepts to be returned.<br>
* </ul>
*
* @return {@link Concepts}
*/
public Concepts getCorpusRelatedConcepts(Map<String, Object> parameters) {
Validate.notNull(parameters.get(ACCOUNT_ID), "account_id can't be null");
Validate.notNull(parameters.get(CORPUS), "corpus can't be null");
String corpusId =
createCorpusIdPath((String) parameters.get(ACCOUNT_ID), (String) parameters.get(CORPUS));
Map<String, Object> queryParameters = new HashMap<String, Object>();
String[] params = new String[] {LEVEL, LIMIT};
for (String param : params) {
if (parameters.containsKey(param)) queryParameters.put(param, parameters.get(param));
}
if (parameters.get(CONCEPT_FIELDS) != null) {
RequestedFields fields = (RequestedFields) parameters.get(CONCEPT_FIELDS);
if (fields != null && fields.getFields() != null && !fields.getFields().isEmpty())
queryParameters.put(CONCEPT_FIELDS, fields.toString());
}
return executeRequest(corpusId + RELATED_CONCEPTS_PATH, queryParameters, Concepts.class);
}
/**
* Searches for graph concepts by using partial matches.<br>
*
* @param parameters The parameters to be used in the service call, account_id, graph and query
* are required.
* <ul>
* <li>String account_id - The account identifier.<br>
* <li>String graph - The graph name.<br>
* <li>String query - The query string.<br>
* <li>Boolean prefix - Whether the query string should be treated as a prefix.<br>
* <li>Integer limit - The maximum number of items to be returned.<br>
* <li>RequestedFields concept_fields - An additional fields to include in the concept
* objects.<br>
* </ul>
*
* @return {@link Matches}
*/
public Matches searchGraphsConceptByLabel(Map<String, Object> parameters) {
Validate.notNull(parameters.get(ACCOUNT_ID), "account_id can't be null");
Validate.notNull(parameters.get(GRAPH), "graph can't be null");
Validate.notNull(parameters.get(QUERY), "query can't be null");
String graph_id =
createGraphIdPath((String) parameters.get(ACCOUNT_ID), (String) parameters.get(GRAPH));
Map<String, Object> queryParameters = new HashMap<String, Object>();
String[] params = new String[] {QUERY, PREFIX, LIMIT};
for (String param : params) {
if (parameters.containsKey(param)) {
queryParameters.put(param, parameters.get(param));
}
}
if (parameters.get(CONCEPT_FIELDS) != null) {
RequestedFields fields = (RequestedFields) parameters.get(CONCEPT_FIELDS);
if (fields != null && fields.getFields() != null && !fields.getFields().isEmpty())
queryParameters.put(CONCEPT_FIELDS, fields.toString());
}
return executeRequest(graph_id + LABEL_SEARCH_PATH, queryParameters, Matches.class);
}
/**
* Searches for graph concepts by using partial matches.
*
* @param parameters The parameters to be used in the service call, account_id, graph are
* required.
* <ul>
* <li>String account_id - The account identifier.<br>
* <li>String graph - The graph name.<br>
* <li>List<String> concepts - Array of concept IDs, each identifying a concept.<br>
* <li>String concept - the concept name.<br>
* <li>Integer level - A number in the range 0 - 3 that represents the level of popularity
* of related concepts.<br>
* <li>Integer limit - The maximum number of concepts to be returned.<br>
* </ul>
*
* @return {@link Concepts}
*/
public Concepts getGraphsRelatedConcepts(Map<String, Object> parameters) {
// TODO: we may need to divide this into 2 methods
Validate.notNull(parameters.get(ACCOUNT_ID), "account_id can't be null");
Validate.notNull(parameters.get(GRAPH), "graph can't be null");
if (parameters.get(CONCEPTS) == null && parameters.get(CONCEPT) == null)
throw new MissingFormatArgumentException("concept or concepts should be identified");
String graphId =
createGraphIdPath((String) parameters.get(ACCOUNT_ID), (String) parameters.get(GRAPH));
Map<String, Object> queryParameters = new HashMap<String, Object>();
String[] queryParms = new String[] {LEVEL, LIMIT};
for (String param : queryParms) {
if (parameters.containsKey(param)) queryParameters.put(param, parameters.get(param));
}
if (parameters.get(CONCEPT_FIELDS) != null) {
RequestedFields fields = (RequestedFields) parameters.get(CONCEPT_FIELDS);
if (fields != null && fields.getFields() != null && !fields.getFields().isEmpty())
queryParameters.put(CONCEPT_FIELDS, fields.toString());
}
if (parameters.get(CONCEPTS) != null) {
JsonObject contentJson = new JsonObject();
JsonArray conceptsJson = new JsonArray();
@SuppressWarnings("unchecked")
List<String> concepts = (List<String>) parameters.get(CONCEPTS);
for (String value : concepts) {
conceptsJson.add(new JsonPrimitive(value));
}
contentJson.add(CONCEPTS, conceptsJson);
queryParameters.put(CONCEPTS, conceptsJson.toString());
return executeRequest(graphId + RELATED_CONCEPTS_PATH, queryParameters, Concepts.class);
} else {
String conceptId =
createConceptIdPath(
(String) parameters.get(ACCOUNT_ID),
(String) parameters.get(GRAPH),
(String) parameters.get(CONCEPT));
return executeRequest(conceptId + RELATED_CONCEPTS_PATH, queryParameters, Concepts.class);
}
}