You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@nlpcraft.apache.org by ar...@apache.org on 2021/08/07 00:22:57 UTC
[incubator-nlpcraft-java-client] branch NLPCRAFT-366 updated: WIP
on NLPCRAFT-366
This is an automated email from the ASF dual-hosted git repository.
aradzinski pushed a commit to branch NLPCRAFT-366
in repository https://gitbox.apache.org/repos/asf/incubator-nlpcraft-java-client.git
The following commit(s) were added to refs/heads/NLPCRAFT-366 by this push:
new 7dd6fdb WIP on NLPCRAFT-366
7dd6fdb is described below
commit 7dd6fdb129557e5f5149ad570806131e6db3a2ca
Author: Nikita Ivanov <>
AuthorDate: Fri Aug 6 17:22:51 2021 -0700
WIP on NLPCRAFT-366
---
.../java/org/apache/nlpcraft/client/NCClient.java | 60 ++++++------
.../java/org/apache/nlpcraft/client/NCElement.java | 109 ++++++++++++++++++++-
.../nlpcraft/client/NCElementSynonymsData.java | 55 ++++++++++-
.../org/apache/nlpcraft/client/NCSuggestion.java | 3 +-
.../apache/nlpcraft/client/NCSuggestionData.java | 3 +-
.../java/org/apache/nlpcraft/client/NCUser.java | 4 +-
6 files changed, 197 insertions(+), 37 deletions(-)
diff --git a/src/main/java/org/apache/nlpcraft/client/NCClient.java b/src/main/java/org/apache/nlpcraft/client/NCClient.java
index b0c514f..ad5c59d 100644
--- a/src/main/java/org/apache/nlpcraft/client/NCClient.java
+++ b/src/main/java/org/apache/nlpcraft/client/NCClient.java
@@ -32,7 +32,7 @@ import java.util.Set;
* <b>External User ID</b><br>
* Several methods on Java client accept external "on-behalf-of" user ID (<code>usrExtId</code>) additionally to the regular
* user ID (<code>usrID</code>). In these methods zero, one or both IDs should be provided. If none are provided
- * the ID of the currently signed in user will be used, and if both are provided they should point to the same user.
+ * the ID of the currently signed-in user will be used, and if both are provided they should point to the same user.
* External user ID allows to use user identification from the external systems without a need to import all the
* existing users into NLPCraft in the first place.
* <p>
@@ -59,25 +59,25 @@ import java.util.Set;
*/
public interface NCClient {
/**
- * Gets current signed in user email for this client.
+ * Gets current signed-in user email for this client.
*
- * @return Current signed in user email for this client.
+ * @return Current signed-in user email for this client.
* @see NCClientBuilder
*/
String getClientUserEmail();
/**
- * Gets current signed in user password for this client.
+ * Gets current signed-in user password for this client.
*
- * @return Current signed in user password for this client.
+ * @return Current signed-in user password for this client.
* @see NCClientBuilder
*/
String getClientUserPassword();
/**
- * Gets whether or not this client is configured with cancel-on-exit logic.
+ * Gets whether this client is configured with cancel-on-exit logic.
*
- * @return Whether or not this client is configured with cancel-on-exit logic
+ * @return Whether this client is configured with cancel-on-exit logic
* @see NCClientBuilder
*/
boolean isClientCancelOnExit();
@@ -95,7 +95,7 @@ public interface NCClient {
* <p>
* <b>User IDs</b><br>
* This method allows multiple ways of specifying the ID of the user. If neither <code>usrId</code>
- * or <code>usrExtId</code> are provided (both are <code>null</code>) then the currently signed in user ID
+ * or <code>usrExtId</code> are provided (both are <code>null</code>) then the currently signed-in user ID
* of this client instance will be used by default. If both user IDs are provided they must identify the same
* user in NLPCraft. If only external "on-behalf-of" <code>usrExtId</code> parameter is provided and such user
* doesn't yet exist in NLPCraft - it will be automatically created. Note that only admin users can specify
@@ -115,7 +115,7 @@ public interface NCClient {
* <p>
* <b>User IDs</b><br>
* This method allows multiple ways of specifying the ID of the user. If neither <code>usrId</code>
- * or <code>usrExtId</code> are provided (both are <code>null</code>) then the currently signed in user ID
+ * or <code>usrExtId</code> are provided (both are <code>null</code>) then the currently signed-in user ID
* of this client instance will be used by default. If both user IDs are provided they must identify the same
* user in NLPCraft. If only external "on-behalf-of" <code>usrExtId</code> parameter is provided and such user
* doesn't yet exist in NLPCraft - it will be automatically created. Note that only admin users can specify
@@ -135,7 +135,7 @@ public interface NCClient {
* <p>
* <b>User IDs</b><br>
* This method allows multiple ways of specifying the ID of the user. If neither <code>usrId</code>
- * or <code>usrExtId</code> are provided (both are <code>null</code>) then the currently signed in user ID
+ * or <code>usrExtId</code> are provided (both are <code>null</code>) then the currently signed-in user ID
* of this client instance will be used by default. If both user IDs are provided they must identify the same
* user in NLPCraft. If only external "on-behalf-of" <code>usrExtId</code> parameter is provided and such user
* doesn't yet exist in NLPCraft - it will be automatically created. Note that only admin users can specify
@@ -169,7 +169,7 @@ public interface NCClient {
* <p>
* <b>User IDs</b><br>
* This method allows multiple ways of specifying the ID of the user. If neither <code>usrId</code>
- * or <code>usrExtId</code> are provided (both are <code>null</code>) then the currently signed in user ID
+ * or <code>usrExtId</code> are provided (both are <code>null</code>) then the currently signed-in user ID
* of this client instance will be used by default. If both user IDs are provided they must identify the same
* user in NLPCraft. If only external "on-behalf-of" <code>usrExtId</code> parameter is provided and such user
* doesn't yet exist in NLPCraft - it will be automatically created. Note that only admin users can specify
@@ -185,7 +185,7 @@ public interface NCClient {
List<NCFeedback> getAllFeedback(String srvReqId, Long usrId, String usrExtId) throws NCClientException, IOException;
/**
- * Adds new user to the company of the currently signed in user. Current signed in user must have
+ * Adds new user to the company of the currently signed-in user. Current signed-in user must have
* administrative privileges.
* <p>
* <b>User IDs</b><br>
@@ -198,7 +198,7 @@ public interface NCClient {
* @param firstName New user first name.
* @param lastName New user last name.
* @param avatarUrl Optional new user avatar URL. Can be {@code null}.
- * @param isAdmin Whether or not the new user will have administrative privileges.
+ * @param isAdmin Whether the new user will have administrative privileges.
* @param properties Map of additional user-defined user properties.
* @param extId Optional external "on-behalf-of" user ID. Can be {@code null}.
* @return ID of the newly created user.
@@ -217,7 +217,7 @@ public interface NCClient {
) throws NCClientException, IOException;
/**
- * Updates given user. Current signed in user must have administrative privileges.
+ * Updates given user. Current signed-in user must have administrative privileges.
*
* @param id User ID.
* @param firstName Mandatory user first name.
@@ -237,7 +237,7 @@ public interface NCClient {
/**
* Resets password for the given user. Note that NLPCraft doesn't store clear text passwords and therefore
- * passwords cannot be retrieved - they can only be reset. Current signed in user must have
+ * passwords cannot be retrieved - they can only be reset. Current signed-in user must have
* administrative privileges.
*
* @param id ID of the user for which to reset the password.
@@ -248,7 +248,7 @@ public interface NCClient {
void resetUserPassword(Long id, String newPasswd) throws NCClientException, IOException;
/**
- * Grants or denies given user administrative privileges. Current signed in user must have
+ * Grants or denies given user administrative privileges. Current signed-in user must have
* administrative privileges.
*
* @param id ID of the user for which to change administrative privileges.
@@ -260,11 +260,11 @@ public interface NCClient {
/**
* Deletes given user. Note that you cannot delete the last admin in the company.
- * Current signed in user must have administrative privileges.
+ * Current signed-in user must have administrative privileges.
* <p>
* <b>User IDs</b><br>
* This method allows multiple ways of specifying the ID of the user. If neither <code>usrId</code>
- * or <code>usrExtId</code> are provided (both are <code>null</code>) then the currently signed in user ID
+ * or <code>usrExtId</code> are provided (both are <code>null</code>) then the currently signed-in user ID
* of this client instance will be used by default. If both user IDs are provided they must identify the same
* user in NLPCraft. If only external "on-behalf-of" <code>usrExtId</code> parameter is provided and such user
* doesn't yet exist in NLPCraft - it will be automatically created. Note that only admin
@@ -283,7 +283,7 @@ public interface NCClient {
* <p>
* <b>User IDs</b><br>
* This method allows multiple ways of specifying the ID of the user. If neither <code>usrId</code>
- * or <code>usrExtId</code> are provided (both are <code>null</code>) then the currently signed in user ID
+ * or <code>usrExtId</code> are provided (both are <code>null</code>) then the currently signed-in user ID
* of this client instance will be used by default. If both user IDs are provided they must identify the same
* user in NLPCraft. If only external "on-behalf-of" <code>usrExtId</code> parameter is provided and such user
* doesn't yet exist in NLPCraft - it will be automatically created. Note that only admin
@@ -298,7 +298,7 @@ public interface NCClient {
NCUser getUser(Long usrId, String usrExtId) throws NCClientException, IOException;
/**
- * Gets all user records for the current signed in user company. Current signed in user must
+ * Gets all user records for the current signed-in user company. Current signed-in user must
* have administrative privileges.
*
* @return List of user records.
@@ -308,8 +308,8 @@ public interface NCClient {
List<NCUser> getAllUsers() throws NCClientException, IOException;
/**
- * Gets all active (connected to the REST server) probes for the current signed in user company.
- * Current signed in user must have administrative privileges.
+ * Gets all active (connected to the REST server) probes for the current signed-in user company.
+ * Current signed-in user must have administrative privileges.
*
* @return List of active probes.
* @throws NCClientException Thrown in case of client-specific errors.
@@ -323,7 +323,7 @@ public interface NCClient {
* <p>
* <b>User IDs</b><br>
* This method allows multiple ways of specifying the ID of the user. If neither <code>usrId</code>
- * or <code>usrExtId</code> are provided (both are <code>null</code>) then the currently signed in user ID
+ * or <code>usrExtId</code> are provided (both are <code>null</code>) then the currently signed-in user ID
* of this client instance will be used by default. If both user IDs are provided they must identify the same
* user in NLPCraft. If only external "on-behalf-of" <code>usrExtId</code> parameter is provided and such user
* doesn't yet exist in NLPCraft - it will be automatically created. Note that only admin
@@ -332,7 +332,7 @@ public interface NCClient {
* @param mdlId ID of the model to submit the request to.
* @param txt Text to process.
* @param data Optional JSON data payload. Can be {@code null} or empty.
- * @param enableLog Whether or not to enable processing log collection.
+ * @param enableLog Whether to enable processing log collection.
* @param usrId Optional user ID.
* @param usrExtId Optional external "on-behalf-of" user ID.
* @return Server request ID of the submitted request.
@@ -366,7 +366,7 @@ public interface NCClient {
* <p>
* <b>User IDs</b><br>
* This method allows multiple ways of specifying the ID of the user. If neither <code>usrId</code>
- * or <code>usrExtId</code> are provided (both are <code>null</code>) then the currently signed in user ID
+ * or <code>usrExtId</code> are provided (both are <code>null</code>) then the currently signed-in user ID
* of this client instance will be used by default. If both user IDs are provided they must identify the same
* user in NLPCraft. If only external "on-behalf-of" <code>usrExtId</code> parameter is provided and such user
* doesn't yet exist in NLPCraft - it will be automatically created. Note that only admin
@@ -375,7 +375,7 @@ public interface NCClient {
* @param mdlId ID of the model to submit the request to.
* @param txt Text to process.
* @param data Optional JSON data payload.
- * @param enableLog Whether or not to enable processing log collection.
+ * @param enableLog Whether to enable processing log collection.
* @param usrId Optional user ID.
* @param usrExtId Optional external "on-behalf-of" user ID.
* @return Query processing result.
@@ -398,7 +398,7 @@ public interface NCClient {
* <p>
* <b>User IDs</b><br>
* This method allows multiple ways of specifying the ID of the user. If neither <code>usrId</code>
- * or <code>usrExtId</code> are provided (both are <code>null</code>) then the currently signed in user ID
+ * or <code>usrExtId</code> are provided (both are <code>null</code>) then the currently signed-in user ID
* of this client instance will be used by default. If both user IDs are provided they must identify the same
* user in NLPCraft. If only external "on-behalf-of" <code>usrExtId</code> parameter is provided and such user
* doesn't yet exist in NLPCraft - it will be automatically created. Note that only admin
@@ -427,7 +427,7 @@ public interface NCClient {
* <p>
* <b>User IDs</b><br>
* This method allows multiple ways of specifying the ID of the user. If neither <code>usrId</code>
- * or <code>usrExtId</code> are provided (both are <code>null</code>) then the currently signed in user ID
+ * or <code>usrExtId</code> are provided (both are <code>null</code>) then the currently signed-in user ID
* of this client instance will be used by default. If both user IDs are provided they must identify the same
* user in NLPCraft. If only external "on-behalf-of" <code>usrExtId</code> parameter is provided and such user
* doesn't yet exist in NLPCraft - it will be automatically created. Note that only admin
@@ -481,7 +481,7 @@ public interface NCClient {
) throws NCClientException, IOException;
/**
- * Gets the company descriptor for the current signed in user.
+ * Gets the company descriptor for the current signed-in user.
*
* @return Company descriptor.
* @throws NCClientException Thrown in case of client-specific errors.
@@ -490,7 +490,7 @@ public interface NCClient {
NCCompany getCompany() throws NCClientException, IOException;
/**
- * Updates company information for the current signed in user. Current signed in user must have
+ * Updates company information for the current signed-in user. Current signed-in user must have
* administrative privileges. Note that users cannot update or get information about other
* companies.
*
diff --git a/src/main/java/org/apache/nlpcraft/client/NCElement.java b/src/main/java/org/apache/nlpcraft/client/NCElement.java
index 4c315bd..d06c086 100644
--- a/src/main/java/org/apache/nlpcraft/client/NCElement.java
+++ b/src/main/java/org/apache/nlpcraft/client/NCElement.java
@@ -21,23 +21,130 @@ import java.util.List;
import java.util.Map;
import java.util.Optional;
-// TODO: like a model NCElement without getValueLoader
+/**
+ * A model's element descriptor.
+ *
+ * @see NCModelInfo#getElements()
+ */
public interface NCElement {
+ /**
+ * Gets unique ID of this element.
+ * <p>
+ * This unique ID should be human-readable for simpler debugging and testing of the model.
+ * Although element ID could be any arbitrary string it is highly recommended having
+ * element ID as a lower case string starting with some model prefix, followed by colon and
+ * then the element's name. For example, some built-in NLPCraft IDs are: <code>nlpcraft:date</code>,
+ * <code>nlpcraft:city</code>.
+ *
+ * @return Unique ID of this element.
+ */
String getId();
+ /**
+ * Gets the list of groups this element belongs to.
+ * <p>
+ * Model element can belong to one or more groups. By default, the element belongs to a single group whose group
+ * ID is equal to its {@link #getId() ID}.
+ *
+ * @return List of groups this element belongs to. By default, the model element belongs to one group
+ * with ID equal to the element {@link #getId() ID}.
+ * @see #getId()
+ */
List<String> getGroups();
+ /**
+ * Gets optional user-defined element's metadata.
+ *
+ * @return Element's metadata or empty collection if none provided. implementation return empty collection.
+ */
Map<String, Object> getMetadata();
+ /**
+ * Gets optional element description.
+ *
+ * @return Optional element description. implementation returns {@code null}.
+ */
String getDescription();
+ /**
+ * Gets optional map of {@link NCValue values} for this element.
+ * <p>
+ * Each element can generally be recognized either by one of its synonyms or values. Elements and their values
+ * are analogous to types and instances of that type in programming languages. Each value
+ * has a name and optional set of its own synonyms by which that value, and ultimately its element, can be
+ * recognized by. Note that value name itself acts as an implicit synonym even when no additional synonyms added
+ * for that value.
+ * <p>
+ * Consider this example. A model element {@code x:car} can have:
+ * <ul>
+ * <li>
+ * Set of general synonyms:
+ * <code>{transportation|transport|_} {vehicle|car|sedan|auto|automobile|suv|crossover|coupe|truck}</code>
+ * </li>
+ * <li>Set of values:
+ * <ul>
+ * <li>{@code mercedes} with synonyms {@code (mercedes, mercedes-benz, mb, benz)}</li>
+ * <li>{@code bmw} with synonyms {@code (bmw, bimmer)}</li>
+ * <li>{@code chevrolet} with synonyms {@code (chevy, chevrolet)}</li>
+ * </ul>
+ * </li>
+ * </ul>
+ * With that setup {@code x:car} element will be recognized by any of the following input sub-string:
+ * <ul>
+ * <li>{@code transport car}</li>
+ * <li>{@code benz}</li>
+ * <li>{@code automobile}</li>
+ * <li>{@code transport vehicle}</li>
+ * <li>{@code sedan}</li>
+ * <li>{@code chevy}</li>
+ * <li>{@code bimmer}</li>
+ * <li>{@code x:car}</li>
+ * </ul>
+ *
+ * @return Map of value's name and its synonyms or {@code null} if not defined.
+ */
List<NCValue> getValues();
+ /**
+ * Gets optional ID of the immediate parent element. Parent ID allows model elements to form into hierarchy.
+ *
+ * @return Optional parent element ID, or {@code null} if not specified. implementation returns
+ * {@code null}.
+ */
String getParentId();
+ /**
+ * Gets the list of synonyms by which this model element will be recognized by. Read more about
+ * many forms of synonyms in <a target=_ href="https://nlpcraft.apache.org/data-model.html">Data Model</a> section
+ * and review <a target=_ href="https://github.com/apache/incubator-nlpcraft/tree/master/nlpcraft-examples">examples</a>.
+ *
+ * @return List of synonyms for this element. List is generally optional since element's ID acts
+ * as an implicit synonym. implementation returns an empty list.
+ */
List<String> getSynonyms();
+ /**
+ * Whether to permutate multi-word synonyms. Automatic multi-word synonyms permutations greatly
+ * increase the total number of synonyms in the system and allows for better multi-word synonym detection.
+ * For example, if permutation is allowed the synonym "a b c" will be automatically converted into a
+ * sequence of synonyms of "a b c", "b a c", "a c b".
+ * <p>
+ * This property overrides the value from {@link NCModelInfo#isPermutateSynonyms()}.
+ * One should use this property if model's value isn't applicable to this element.
+ *
+ * @return Optional synonym permutate property overriding model's one.
+ * @see NCModelInfo#isPermutateSynonyms()
+ */
Optional<Boolean> isPermutateSynonyms();
+ /**
+ * Whether this element allows the non-stop words gaps in its multi-word synonyms.
+ * <p>
+ * This property overrides the value from {@link NCModelInfo#isSparse()}.
+ * One should use this property if model's value isn't applicable to this element.
+ *
+ * @return Optional multi-word synonym sparsity property overriding model's one.
+ * @see NCModelInfo#isSparse()
+ */
Optional<Boolean> isSparse();
}
diff --git a/src/main/java/org/apache/nlpcraft/client/NCElementSynonymsData.java b/src/main/java/org/apache/nlpcraft/client/NCElementSynonymsData.java
index 668a27c..5af5357 100644
--- a/src/main/java/org/apache/nlpcraft/client/NCElementSynonymsData.java
+++ b/src/main/java/org/apache/nlpcraft/client/NCElementSynonymsData.java
@@ -21,15 +21,66 @@ import java.util.List;
import java.util.Map;
/**
- * TODO:
+ * A model element synonyms data descriptor.
+ *
+ * @see NCClient#getSynonyms(String, String)
*/
public interface NCElementSynonymsData {
+ /**
+ * Gets number of synonyms (in their unexpanded forms) for the element.
+ *
+ * @return Number of synonyms (in their unexpanded forms) for the element.
+ * @see #getSynonymsExpCnt()
+ */
int getSynonymsCnt();
+
+ /**
+ * Gets number of expanded synonyms for the element.
+ *
+ * @return Number of expanded synonyms for the element.
+ * @see #getSynonymsCnt()
+ */
int getSynonymsExpCnt();
+
+ /**
+ * Gets the rate of number of expanded synonyms over the non-expanded ones.
+ * The return value is always greater than 1.
+ *
+ * @return Rate of number of expanded synonyms over the non-expanded ones.
+ * @see #getSynonymsCnt()
+ * @see #getSynonymsExpCnt()
+ */
long getSynonymsExpRatePct();
+ /**
+ * Gets the list of non-expanded synonyms for this element.
+ *
+ * @return List of non-expanded synonyms for this element.
+ * @see #getSynonymsExp()
+ */
List<String> getSynonyms();
+
+ /**
+ * Gets the list of expanded synonyms for this element.
+ *
+ * @return List of expanded synonyms for this element.
+ * @see #getSynonyms()
+ */
List<String> getSynonymsExp();
+
+ /**
+ * Get the map of values and their non-expanded synonyms.
+ *
+ * @return Map of values and their non-expanded synonyms.
+ * @see #getValuesExp()
+ */
Map<String, List<String>> getValues();
+
+ /**
+ * Get the map of values and their expanded synonyms.
+ *
+ * @return Map of values and their expanded synonyms.
+ * @see #getValues()
+ */
Map<String, List<String>> getValuesExp();
-}
+}
\ No newline at end of file
diff --git a/src/main/java/org/apache/nlpcraft/client/NCSuggestion.java b/src/main/java/org/apache/nlpcraft/client/NCSuggestion.java
index cb90f1c..dd53361 100644
--- a/src/main/java/org/apache/nlpcraft/client/NCSuggestion.java
+++ b/src/main/java/org/apache/nlpcraft/client/NCSuggestion.java
@@ -18,9 +18,10 @@
package org.apache.nlpcraft.client;
/**
- * Individual synonym suggestion returned from {@link NCSuggestionData#getSynonyms()} method.
+ * Individual synonym suggestion.
*
* @see <a href="https://nlpcraft.apache.org/tools/syn_tool.html">Synonym suggestion tool</a>.
+ * @see NCSuggestionData#getSynonyms()
*/
public interface NCSuggestion {
/**
diff --git a/src/main/java/org/apache/nlpcraft/client/NCSuggestionData.java b/src/main/java/org/apache/nlpcraft/client/NCSuggestionData.java
index 967b7f0..56c7e3c 100644
--- a/src/main/java/org/apache/nlpcraft/client/NCSuggestionData.java
+++ b/src/main/java/org/apache/nlpcraft/client/NCSuggestionData.java
@@ -21,9 +21,10 @@ import java.util.List;
import java.util.Map;
/**
- * Result container returned by {@link NCClient#suggestSynonyms(String, Double)} method.
+ * Synonym suggestion tool result descriptor.
*
* @see <a href="https://nlpcraft.apache.org/tools/syn_tool.html">Synonym suggestion tool</a>.
+ * @see NCClient#suggestSynonyms(String, Double)
*/
public interface NCSuggestionData {
/**
diff --git a/src/main/java/org/apache/nlpcraft/client/NCUser.java b/src/main/java/org/apache/nlpcraft/client/NCUser.java
index 6943bf1..fb6242e 100644
--- a/src/main/java/org/apache/nlpcraft/client/NCUser.java
+++ b/src/main/java/org/apache/nlpcraft/client/NCUser.java
@@ -62,9 +62,9 @@ public interface NCUser {
String getAvatarUrl();
/**
- * Gets whether or not this user has administrative privileges.
+ * Gets whether this user has administrative privileges.
*
- * @return Whether or not this user has administrative privileges.
+ * @return Whether this user has administrative privileges.
*/
boolean isAdmin();