com.raritantechnologies.recommend.Verity
Class VerityRecommend

java.lang.Object
  com.raritantechnologies.recommend.Verity.VerityRecommend

All Implemented Interfaces:

IConfigurable, IRecommend

public class VerityRecommend

extends java.lang.Object

implements IRecommend

Class for utilizing the Verity K2 recommendation features

The class has methods for pushing data to the recommendation engine as well as methods for retreiving users/documents/queries based on various inputs

XML Configuration Template:

    <RecommendImpl class="com.raritantechnologies.recommend.Verity.VerityRecommend"
		k2ServerSpec="[ Verity K2 Server host:port ]"
 	
		queryRecommendationIndexType="[ Type of recommendation index for queries ]"
 		queryRecommendationIndexAlias="[ Alias of query recommendation index ]"
 
 		userGroupRecommendationIndexType="[ Type of recommendation index for user group ]"
 		userGroupRecommendationIndexAlias="[ Alias of user group recommendation index ]"
 	
 		queryGroupRecommendationIndexType="[ Type of recommendation index for query group ]"
 		queryGroupRecommendationIndexAlias="[ Alias of query group recommendation index ]"
 	
 		queryParser="[ Valid Verity query parser - "FreeText" "Simple" "BoolPlus" ]"

 		<VQLParserStringFilter 
			outputFormat="[type of filter to apply to queries - RulesValueString or ToEnglishString]" />

    </RecommendImpl>
 

Author:

Ron Pohle

Field Summary

static java.lang.String	CREATE_ALL_RELATIONSHIPS Transaction type for creating all relationships.
static java.lang.String	DOC_AND_QUERY_TO_USER Transaction type for associating a document and query to a user.
static java.lang.String	DOC_AND_QUERY_TO_USER_GROUP Transaction type for associating a document and a query to a user group.
static java.lang.String	DOC_TO_QUERY Transaction type for associating a document to a query.
static java.lang.String	GET_QUERIES
static java.lang.String	QUERY_TO_DOC Transaction type for associating a query to a document.
static java.lang.String	QUERY_TO_QUERY_GROUP Transaction type for associating a query to a query group.

Constructor Summary

VerityRecommend()

Method Summary

void	addDocuments(ILoginInfo userInfo, OrderedMap queryMap, IDocument[] document) Not used for K2 implementation of recommendation.
void	addQuery(ILoginInfo userInfo, OrderedMap queryMap) Not used for K2 implementation of recommendation.
void	addUser(ILoginInfo userInfo) Not used for K2 implementation of recommendation.
void	createNewLogEntity(java.lang.String riType, java.lang.String entityID) createNewLogEntity is public so that a batch update program can use it.
void	createRecommendationLogEntries(java.lang.String transactionType, OrderedMap transMap) Creates and submits a transaction to the Verity K2 recommendation log(s).
ILoginInfo[]	getExpertUsers(IQueryList queries, IDocument document, int returnCount) Retreives users that match the query/document specified.
IDocument[]	getRelatedDocuments(java.util.Collection repositories, java.util.Collection docFields, ILoginInfo userInfo, boolean isGroup, int returnCount) Retreives documents that match the user or user group specified.
IDocument[]	getRelatedDocuments(java.util.Collection repositories, java.util.Collection docFields, ILoginInfo userInfo, IDocument document, OrderedMap queryMap, boolean isGroup, int returnCount) Retreives documents that match the user or group/document/query specified.
IQueryList	getRelatedQueries(java.util.Collection repositories, ILoginInfo userInfo, IQueryList queries, IDocument document, boolean isGroup, int returnCount) Retreives queries that match the user or group/document/query specified.
IQueryList	getRelatedQueries(ILoginInfo userInfo, boolean isGroup, int returnCount) Retreives queries that match the user/group specified.
ILoginInfo[]	getRelatedUsers(ILoginInfo userInfo, OrderedMap queryMap, boolean isGroup, int returnCount) Retreives users that match the user or group/query specified.
void	initialize(org.w3c.dom.Element elem) Sets variable values from the RecommendationWebServicesConfig.xml file
IDocument[]	recommendDocuments(java.util.Collection repositories, java.util.Collection docFields, OrderedMap queryMap, ILoginInfo userInfo, int returnCount) Retreives documents that match the query/user specified.
IDocument[]	recommendSimilarDocuments(java.util.Collection repositories, java.util.Collection docFields, OrderedMap queryMap, IDocument document, int returnCount) Retreives documents that match the document/query specified.

Methods inherited from class java.lang.Object

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

Field Detail

DOC_AND_QUERY_TO_USER

public static final java.lang.String DOC_AND_QUERY_TO_USER

Transaction type for associating a document and query to a user.

Requires the transMap contain a TargetValue and a TargetWeight describing the target user. SourceValue1/SourceWeight1 describe the document. SourceValue2/SourceWeight2 describe the query.

An example:
TargetValue=Tom
TargetWeight=100
SourceValue1=1234@doccollection
SourceWeight1=65
SourceValue2=automobile
SourceWeight2=85

See Also:

createRecommendationLogEntries(java.lang.String, com.raritantechnologies.utils.OrderedMap), Constant Field Values

QUERY_TO_DOC

public static final java.lang.String QUERY_TO_DOC

Transaction type for associating a query to a document.

Requires the transMap contain a TargetValue and a TargetWeight describing the target document. SourceValue1/SourceWeight1 describe the query.

An example:
TargetValue=1234@doccollection
TargetWeight=100
SourceValue1=automobile
SourceWeight1=65

See Also:

createRecommendationLogEntries(java.lang.String, com.raritantechnologies.utils.OrderedMap), Constant Field Values

DOC_TO_QUERY

public static final java.lang.String DOC_TO_QUERY

Transaction type for associating a document to a query.

Requires the transMap contain a TargetValue and a TargetWeight describing the target query. SourceValue1/SourceWeight1 describe the document.

An example:
TargetValue=automobile
TargetWeight=100
SourceValue1=1234@doccollection
SourceWeight1=65

See Also:

createRecommendationLogEntries(java.lang.String, com.raritantechnologies.utils.OrderedMap), Constant Field Values

DOC_AND_QUERY_TO_USER_GROUP

public static final java.lang.String DOC_AND_QUERY_TO_USER_GROUP

Transaction type for associating a document and a query to a user group.

Requires the transMap contain a TargetValue and a TargetWeight describing the target user group. SourceValue1/SourceWeight1 describe the document. SourceValue2/SourceWeight2 describe the query.

An example:
TargetValue=All
TargetWeight=100
SourceValue1=1234@doccollection
SourceWeight1=65
SourceValue2=automobile
SourceWeight2=85

See Also:

createRecommendationLogEntries(java.lang.String, com.raritantechnologies.utils.OrderedMap), Constant Field Values

QUERY_TO_QUERY_GROUP

public static final java.lang.String QUERY_TO_QUERY_GROUP

Transaction type for associating a query to a query group.

Requires the transMap contain a TargetValue and a TargetWeight describing the target query group. SourceValue1/SourceWeight1 describe the query.

An example:
TargetValue=All
TargetWeight=100
SourceValue1=automobile
SourceWeight1=65

See Also:

createRecommendationLogEntries(java.lang.String, com.raritantechnologies.utils.OrderedMap), Constant Field Values

CREATE_ALL_RELATIONSHIPS

public static final java.lang.String CREATE_ALL_RELATIONSHIPS

Transaction type for creating all relationships.

Requires the transMap contain a user, group(s), query, document, target weight and source weight.

An example:
User=Tom
Group=All
Query=(frequency metadata)
Document=123@ieejrns
TargetWeight=100
SourceWeight=65

See Also:

createRecommendationLogEntries(java.lang.String, com.raritantechnologies.utils.OrderedMap), Constant Field Values

GET_QUERIES

public static final java.lang.String GET_QUERIES

See Also:

Constant Field Values

Constructor Detail

VerityRecommend

public VerityRecommend()

Method Detail

initialize

public void initialize(org.w3c.dom.Element elem)

Sets variable values from the RecommendationWebServicesConfig.xml file

Specified by:

initialize in interface IConfigurable

addUser

public void addUser(ILoginInfo userInfo)

Not used for K2 implementation of recommendation.

Specified by:

addUser in interface IRecommend

Parameters:

userInfo - contains user name

See Also:

createRecommendationLogEntries(java.lang.String, com.raritantechnologies.utils.OrderedMap)

addQuery

public void addQuery(ILoginInfo userInfo,
                     OrderedMap queryMap)

Not used for K2 implementation of recommendation.

Specified by:

addQuery in interface IRecommend

Parameters:

userInfo - contains user name

queryMap - contains query text

See Also:

createRecommendationLogEntries(java.lang.String, com.raritantechnologies.utils.OrderedMap)

addDocuments

public void addDocuments(ILoginInfo userInfo,
                         OrderedMap queryMap,
                         IDocument[] document)

Not used for K2 implementation of recommendation.

Specified by:

addDocuments in interface IRecommend

Parameters:

userInfo - contains user name

queryMap - contains query text

document - contains documents

See Also:

createRecommendationLogEntries(java.lang.String, com.raritantechnologies.utils.OrderedMap)

createRecommendationLogEntries

public void createRecommendationLogEntries(java.lang.String transactionType,
                                           OrderedMap transMap)
                                    throws RecommendException

Creates and submits a transaction to the Verity K2 recommendation log(s).

The following applies to all transactions except CREATE_ALL_RELATIONSHIPS A K2 recommendation transaction requires one target entity and at least one source entity. A value and a weight are required to build an entity. The transMap must contain a TargetValue and a TargetWeight with their associated data. The transMap must contain SourceValue1 and SourceWeight1 with their associated data. Depending on the transaction type, a SourceValue2 and SourceWeight2 will be required. See the transaction types below for more details.

For transaction CREATE_ALL_RELATIONSHIPS, a user, query, group, document target weight and source weight are used to generate and call the following 5 transactions:
DOC_AND_QUERY_TO_USER
QUERY_TO_DOC
DOC_TO_QUERY
DOC_AND_QUERY_TO_USER_GROUP
QUERY_TO_QUERY_GROUP

Specified by:

createRecommendationLogEntries in interface IRecommend

Parameters:

transactionType - specifies a VerityRecommend transaction type.

transMap - contains target and source data to format a K2 recommendation transaction.

Throws:

RecommendException

See Also:

DOC_AND_QUERY_TO_USER, QUERY_TO_DOC, DOC_TO_QUERY, DOC_AND_QUERY_TO_USER_GROUP, QUERY_TO_QUERY_GROUP, CREATE_ALL_RELATIONSHIPS

getRelatedDocuments

public IDocument[] getRelatedDocuments(java.util.Collection repositories,
                                       java.util.Collection docFields,
                                       ILoginInfo userInfo,
                                       boolean isGroup,
                                       int returnCount)
                                throws RecommendException

Retreives documents that match the user or user group specified.

Specified by:

getRelatedDocuments in interface IRecommend

Parameters:

repositories - recommendation indexes to search

docFields - return specified fields in addition to document ID and URL

userInfo - Use the getUserName method to get seed user or group

isGroup - used to determine if user is a group or individual

returnCount - number of documents to return

Returns:

Throws:

RecommendException

getRelatedDocuments

public IDocument[] getRelatedDocuments(java.util.Collection repositories,
                                       java.util.Collection docFields,
                                       ILoginInfo userInfo,
                                       IDocument document,
                                       OrderedMap queryMap,
                                       boolean isGroup,
                                       int returnCount)
                                throws RecommendException

Retreives documents that match the user or group/document/query specified.

Specified by:

getRelatedDocuments in interface IRecommend

Parameters:

repositories - recommendation indexes to search

docFields - return specified fields in addition to document ID and URL

userInfo - Use the getUserName method to get seed user or group

document - Use the getDocumentID method to get seed document

queryMap - Use the getValue method with a key of 'Query' to get seed query

isGroup - used to determine if user is a group or individual

returnCount - number of documents to return

Returns:

Throws:

RecommendException

recommendSimilarDocuments

public IDocument[] recommendSimilarDocuments(java.util.Collection repositories,
                                             java.util.Collection docFields,
                                             OrderedMap queryMap,
                                             IDocument document,
                                             int returnCount)
                                      throws RecommendException

Retreives documents that match the document/query specified.

Specified by:

recommendSimilarDocuments in interface IRecommend

Parameters:

repositories - recommendation indexes to search

docFields - return specified fields in addition to document ID and URL

queryMap - Use the getValue method with a key of 'Query' to get seed query

document - Use the getDocumentID method to get seed document

returnCount - number of documents to return

Returns:

Throws:

RecommendException

recommendDocuments

public IDocument[] recommendDocuments(java.util.Collection repositories,
                                      java.util.Collection docFields,
                                      OrderedMap queryMap,
                                      ILoginInfo userInfo,
                                      int returnCount)
                               throws RecommendException

Retreives documents that match the query/user specified.

Specified by:

recommendDocuments in interface IRecommend

Parameters:

repositories - recommendation indexes to search

docFields - return specified fields in addition to document ID and URL

queryMap - Use the getValue method with a key of 'Query' to get seed query

userInfo - Use the getUserName method to get the seed user

returnCount - number of documents to return

Returns:

Throws:

RecommendException

getRelatedQueries

public IQueryList getRelatedQueries(ILoginInfo userInfo,
                                    boolean isGroup,
                                    int returnCount)
                             throws RecommendException

Retreives queries that match the user/group specified.

Specified by:

getRelatedQueries in interface IRecommend

Parameters:

userInfo - Use the getUserName method to get the seed user

isGroup - used to determine if user is a group or individual

returnCount - number of documents to return

Returns:

Throws:

RecommendException

getRelatedQueries

public IQueryList getRelatedQueries(java.util.Collection repositories,
                                    ILoginInfo userInfo,
                                    IQueryList queries,
                                    IDocument document,
                                    boolean isGroup,
                                    int returnCount)
                             throws RecommendException

Retreives queries that match the user or group/document/query specified.

Specified by:

getRelatedQueries in interface IRecommend

Parameters:

repositories - recommendation indexes to search

userInfo - Use the getUserName method to get seed user or group

queries - Use the getQueryFromMap method to get seed query

document - Use the getDocumentID method to get seed document

isGroup - used to determine if user is a group or individual

returnCount - number of documents to return

Returns:

Throws:

RecommendException

getExpertUsers

public ILoginInfo[] getExpertUsers(IQueryList queries,
                                   IDocument document,
                                   int returnCount)
                            throws RecommendException

Retreives users that match the query/document specified.

Specified by:

getExpertUsers in interface IRecommend

Parameters:

queries - Use the getQueryFromMap method to get seed query

document - Use the getDocumentID method to get seed document

returnCount - number of documents to return

Returns:

Throws:

RecommendException

getRelatedUsers

public ILoginInfo[] getRelatedUsers(ILoginInfo userInfo,
                                    OrderedMap queryMap,
                                    boolean isGroup,
                                    int returnCount)
                             throws RecommendException

Retreives users that match the user or group/query specified.

Specified by:

getRelatedUsers in interface IRecommend

Parameters:

userInfo - Use the getUserName method to get seed user or group

queryMap - Use the getQueryFromMap method to get seed query

isGroup - used to determine if user is a group or individual

returnCount - number of documents to return

Returns:

Throws:

RecommendException

createNewLogEntity

public void createNewLogEntity(java.lang.String riType,
                               java.lang.String entityID)
                        throws RecommendException

createNewLogEntity is public so that a batch update program can use it. The batch update program is used to load seed data into the recommendation engine.

This method first checks if the entity exists. If the entity is not found a TX_NEW transaction is created to establish the entity. This method can not create an entity of type 'doc'. Documents must be created in the document collection. The mkre -update would then create the entity in the recommendation index.

The entity must be fully qualified. The format is: entity@alias where entity is the entity to be created and alias is the alias of the recommendation index. To create a user, the riType would be 'user' and the entityID would be 'Tom@users'.

Parameters:

riType - recommendation index type of entity to be created

entityID - entity to be created

Throws:

RecommendException