Merge branch 'concept-expansion' into dev

Author: germanattanasio

README.md

@@ -19,6 +19,7 @@ APIs and SDKs that use cognitive computing to solve complex problems.
     * [Alchemy Language](#alchemy-language)
     * [Alchemy Vision](#alchemy-vision)
     * [Alchemy Data News](#alchemy-data-news)
+    * [Concept Expansion](#concept-expansion)
     * [Concept Insights](#concept-insights)
     * [Dialog](#dialog)
     * [Document Conversion](#document-conversion)
@@ -158,6 +159,32 @@ DocumentsResult result = service.getNewsDocuments(params);
 System.out.println(result);
 ```
 
+### Concept Expansion
+Map euphemisms or colloquial terms to more commonly understood phrases using
+the [Concept Expansion][concept_expansion] service.
+Example: Create a job, wait for it to finish, and then retrieve results.
+
+```java
+ConceptExpansion service = new ConceptExpansion();
+service.setUsernameAndPassword("<username>", "<password>");
+
+String[] seeds = new String[]{ "motrin", "tylenol", "aspirin"};
+String label = "medicine";
+Job job = service.createJob(label, seeds);
+
+while (service.getJobStatus(job) == Job.Status.AWAITING_WORK
+		|| service.getJobStatus(job) == Job.Status.IN_FLIGHT) {
+	try {
+		Thread.sleep(4000);
+	} catch (InterruptedException e) {
+		e.printStackTrace();
+	}
+}
+
+System.out.println(service.getJobResult(job));
+```
+
+
 ### Concept Insights
 Use the [Concept Insights][concept_insights] service to identify words in the text that
 correspond to concepts in a Wikipedia graph.
@@ -508,6 +535,7 @@ See [CONTRIBUTING.md](CONTRIBUTING.md).
 [concept_insights]: https://www.ibm.com/smarterplanet/us/en/ibmwatson/developercloud/doc/concept-insights/
 [visual_insights]: http://www.ibm.com/smarterplanet/us/en/ibmwatson/developercloud/doc/visual-insights/
 [retrieve_and_rank]: http://www.ibm.com/smarterplanet/us/en/ibmwatson/developercloud/doc/retrieve-rank/
+[concept_expansion]: http://www.ibm.com/smarterplanet/us/en/ibmwatson/developercloud/doc/concept-expansion/
 
 [alchemy_language]: http://www.alchemyapi.com/products/alchemylanguage
 [sentiment_analysis]: http://www.alchemyapi.com/products/alchemylanguage/sentiment-analysis

examples/java/com/ibm/watson/developer_cloud/concept_expansion/v1/ConceptExpansionExample.java

@@ -0,0 +1,41 @@
+/**
+ * Copyright 2015 IBM Corp. All Rights Reserved.
+ * 
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
+ * in compliance with the License. You may obtain a copy of the License at
+ * 
+ * http://www.apache.org/licenses/LICENSE-2.0
+ * 
+ * Unless required by applicable law or agreed to in writing, software distributed under the License
+ * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
+ * or implied. See the License for the specific language governing permissions and limitations under
+ * the License.
+ */
+package com.ibm.watson.developer_cloud.concept_expansion.v1;
+
+import com.ibm.watson.developer_cloud.concept_expansion.v1.model.Job;
+
+public class ConceptExpansionExample {
+
+
+  public static void main(String[] args) {
+    final ConceptExpansion service = new ConceptExpansion();
+    service.setUsernameAndPassword("<username>", "<password>");
+
+    final String[] seeds = new String[] {"nyc", "dc", "london", "big cities"};
+    final String label = "demo";
+
+    final Job job = service.createJob(label, seeds);
+
+    while (service.getJobStatus(job) == Job.Status.AWAITING_WORK
+        || service.getJobStatus(job) == Job.Status.IN_FLIGHT) {
+      try {
+        Thread.sleep(4000);
+      } catch (final InterruptedException e) {
+        e.printStackTrace();
+      }
+    }
+
+    System.out.println(service.getJobResult(job));
+  }
+}

src/main/java/com/ibm/watson/developer_cloud/concept_expansion/v1/ConceptExpansion.java

@@ -0,0 +1,185 @@
+/**
+ * Copyright 2015 IBM Corp. All Rights Reserved.
+ * 
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
+ * in compliance with the License. You may obtain a copy of the License at
+ * 
+ * http://www.apache.org/licenses/LICENSE-2.0
+ * 
+ * Unless required by applicable law or agreed to in writing, software distributed under the License
+ * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
+ * or implied. See the License for the specific language governing permissions and limitations under
+ * the License.
+ */
+package com.ibm.watson.developer_cloud.concept_expansion.v1;
+
+import java.util.ArrayList;
+import java.util.List;
+
+import com.google.gson.JsonArray;
+import com.google.gson.JsonElement;
+import com.google.gson.JsonObject;
+import com.google.gson.JsonParser;
+import com.google.gson.JsonPrimitive;
+import com.ibm.watson.developer_cloud.concept_expansion.v1.model.Concept;
+import com.ibm.watson.developer_cloud.concept_expansion.v1.model.Dataset;
+import com.ibm.watson.developer_cloud.concept_expansion.v1.model.Job;
+import com.ibm.watson.developer_cloud.concept_expansion.v1.model.Job.Status;
+import com.ibm.watson.developer_cloud.http.RequestBuilder;
+import com.ibm.watson.developer_cloud.service.WatsonService;
+import com.ibm.watson.developer_cloud.util.ResponseUtil;
+import com.ibm.watson.developer_cloud.util.Validate;
+import com.squareup.okhttp.Request;
+import com.squareup.okhttp.Response;
+
+/**
+ * The Concept Expansion service analyzes text and interprets its meaning based on usage in other
+ * similar contexts.
+ * 
+ * @version v1
+ * @see <a
+ *      href="http://www.ibm.com/smarterplanet/us/en/ibmwatson/developercloud/concept-expansion.html">
+ *      Concept Expansion</a>
+ */
+public class ConceptExpansion extends WatsonService {
+  private static final String DATASET = "dataset";
+  private static final String LABEL = "label";
+  private static final String PARAM_JOBID = "jobid";
+  private static final String PARAM_STATE = "state";
+  private static final String PREVALENCE = "prevalence";
+  private static final String RESULT = "result";
+  private static final String RETURN_SEEDS = "return_seeds";
+  private static final String SEEDS = "seeds";
+  private static String URL = "https://gateway.watsonplatform.net/concept-expansion-beta/api";
+  private static final String V1_RESULT = "/v1/result";
+  private static final String V1_STATUS = "/v1/status";
+  private static final String V1_UPLOAD = "/v1/upload";
+
+  private Dataset dataset;
+
+  /**
+   * Instantiates a new Concept Expansion service.
+   * 
+   */
+  public ConceptExpansion() {
+    super("concept_expansion");
+    setEndPoint(URL);
+    setDataset(Dataset.MT_SAMPLES);
+  }
+
+  /**
+   * Creates a {@link Job}.
+   * 
+   * @param label A conceptual classification of the seed terms.
+   * @param seeds List of terms to be used as seeds
+   * 
+   * @return the {@link Job}
+   */
+  public Job createJob(final String label, final String[] seeds) {
+    Validate.notEmpty(label, "label cannot be null or empty");
+    Validate.notEmpty(seeds, "seeds cannot be null or empty");
+    Validate.notNull(dataset, "dataset cannot be null");
+
+    final JsonArray seedJsonArray = new JsonArray();
+    for (final String seed : seeds) {
+      seedJsonArray.add(new JsonPrimitive(seed));
+    }
+
+    final JsonObject payload = new JsonObject();
+    payload.addProperty(LABEL, label);
+    payload.addProperty(DATASET, dataset.getId());
+    payload.add(SEEDS, seedJsonArray);
+
+    final Request request = RequestBuilder.post(V1_UPLOAD).withBodyJson(payload).build();
+    return executeRequest(request, Job.class);
+  }
+
+  /**
+   * Formats a concept {@link JsonObject} as a {@link Concept} object
+   * 
+   * @param conceptJson the concept as {@link JsonObject}
+   * 
+   *        <pre>
+   * <code> { result:"apple", prevalence:"20" }</code>
+   * </pre>
+   * @return the concept as POJO Object
+   */
+  private Concept formatConcept(JsonObject conceptJson) {
+    return new Concept(conceptJson.get(RESULT).getAsString(), conceptJson.get(PREVALENCE)
+        .getAsDouble());
+  }
+
+  /**
+   * Map JSON concepts to POJO Objects.
+   * 
+   * @param conceptsJson the concepts as json
+   * @return the list
+   */
+  private List<Concept> formatConcepts(JsonObject conceptsJson) {
+    final JsonArray conceptArray = conceptsJson.get(RETURN_SEEDS).getAsJsonArray();
+    final List<Concept> concepts = new ArrayList<Concept>();
+
+    for (final JsonElement conceptJson : conceptArray) {
+      concepts.add(formatConcept(conceptJson.getAsJsonObject()));
+    }
+    return concepts;
+  }
+
+  /**
+   * Gets the dataset.
+   * 
+   * @return the dataset
+   */
+  public Dataset getDataset() {
+    return dataset;
+  }
+
+  /**
+   * Gets the {@link Job} result.
+   * 
+   * @param job the {@link Job}
+   * 
+   * @return the list of concepts
+   * @see Concept
+   * @see Job
+   */
+  public List<Concept> getJobResult(final Job job) {
+    Validate.notNull(job, "job cannot be null");
+
+    final JsonObject payload = new JsonObject();
+    payload.addProperty(PARAM_JOBID, job.getId());
+
+    final Request request = RequestBuilder.put(V1_RESULT).withBodyJson(payload).build();
+
+    final String resultAsString = ResponseUtil.getString(execute(request));
+    return formatConcepts(new JsonParser().parse(resultAsString).getAsJsonObject());
+  }
+
+  /**
+   * Gets the {@link Job} status.
+   * 
+   * @param job the {@link Job}
+   * 
+   * @return the job status
+   */
+  public Status getJobStatus(final Job job) {
+    Validate.notNull(job, "job cannot be null");
+
+    final Request request =
+        RequestBuilder.get(V1_STATUS).withQuery(PARAM_JOBID, job.getId()).build();
+
+    final Response response = execute(request);
+    final JsonObject jsonObject = ResponseUtil.getJsonObject(response);
+    return Status.fromString(jsonObject.get(PARAM_STATE).getAsString());
+  }
+
+  /**
+   * Sets the Dataset to run against.
+   * 
+   * @param dataset the new dataset
+   */
+  public void setDataset(final Dataset dataset) {
+    this.dataset = dataset;
+  }
+
+}

src/main/java/com/ibm/watson/developer_cloud/concept_expansion/v1/model/Concept.java

@@ -0,0 +1,65 @@
+/**
+ * Copyright 2015 IBM Corp. All Rights Reserved.
+ * 
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
+ * in compliance with the License. You may obtain a copy of the License at
+ * 
+ * http://www.apache.org/licenses/LICENSE-2.0
+ * 
+ * Unless required by applicable law or agreed to in writing, software distributed under the License
+ * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
+ * or implied. See the License for the specific language governing permissions and limitations under
+ * the License.
+ */
+
+package com.ibm.watson.developer_cloud.concept_expansion.v1.model;
+
+import com.ibm.watson.developer_cloud.concept_expansion.v1.ConceptExpansion;
+import com.ibm.watson.developer_cloud.service.model.GenericModel;
+
+/**
+ * This class map a Concept returned by {@link ConceptExpansion}.
+ * 
+ * @author German Attanasio Ruiz (germanatt@us.ibm.com)
+ */
+public class Concept extends GenericModel {
+
+  /** The name. */
+  private final String name;
+
+  /** The prevalence. */
+  private final Double prevalence;
+
+  /**
+   * Instantiates a new concept.
+   * 
+   * @param name the name
+   * @param prevalence the prevalence
+   */
+  public Concept(String name, Double prevalence) {
+    super();
+    this.name = name;
+    this.prevalence = prevalence;
+  }
+
+  /**
+   * Gets the name.
+   * 
+   * 
+   * @return the name
+   */
+  public String getName() {
+    return name;
+  }
+
+  /**
+   * Gets the prevalence.
+   * 
+   * 
+   * @return the prevalence
+   */
+  public Double getPrevalence() {
+    return prevalence;
+  }
+
+}