http://git-wip-us.apache.org/repos/asf/incubator-unomi/blob/dc1d1520/api/src/main/java/org/apache/unomi/api/services/EventListenerService.java ---------------------------------------------------------------------- diff --git a/api/src/main/java/org/apache/unomi/api/services/EventListenerService.java b/api/src/main/java/org/apache/unomi/api/services/EventListenerService.java new file mode 100644 index 0000000..00bccb0 --- /dev/null +++ b/api/src/main/java/org/apache/unomi/api/services/EventListenerService.java @@ -0,0 +1,46 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You 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 org.apache.unomi.api.services; + +import org.apache.unomi.api.Event; + +/** + * A service that gets notified (via {@link #onEvent(Event)}) whenever an event it can handle as decided by {@link #canHandle(Event)} occurs in the context server. + */ +public interface EventListenerService { + + /** + * Whether or not this listener can handle the specified event. + * + * @param event the event to be handled + * @return {@code true} if this listener can handle the specified event, {@code false} otherwise + */ + boolean canHandle(Event event); + + /** + * Handles the specified event. + * + * @param event the event to be handled + * @return the result of the event handling as combination of {@link EventService} flags, to be checked using bitwise AND (&) operator + * @see EventService#NO_CHANGE + * @see EventService#PROFILE_UPDATED + * @see EventService#SESSION_UPDATED + */ + int onEvent(Event event); + +}
http://git-wip-us.apache.org/repos/asf/incubator-unomi/blob/dc1d1520/api/src/main/java/org/apache/unomi/api/services/EventService.java ---------------------------------------------------------------------- diff --git a/api/src/main/java/org/apache/unomi/api/services/EventService.java b/api/src/main/java/org/apache/unomi/api/services/EventService.java new file mode 100644 index 0000000..fe81130 --- /dev/null +++ b/api/src/main/java/org/apache/unomi/api/services/EventService.java @@ -0,0 +1,109 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You 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 org.apache.unomi.api.services; + +import org.apache.unomi.api.Event; +import org.apache.unomi.api.EventProperty; +import org.apache.unomi.api.PartialList; +import org.apache.unomi.api.Session; +import org.apache.unomi.api.actions.ActionPostExecutor; +import org.apache.unomi.api.conditions.Condition; + +import java.util.List; +import java.util.Set; + +/** + * A service to publish events, notably issued from user interactions with tracked entities, in the context server. + */ +public interface EventService { + + /** + * No change occurred following an event being handled. + */ + int NO_CHANGE = 0; + /** + * The associated session was updated following an event being handled. + */ + int SESSION_UPDATED = 1; + /** + * The associated profile was updated following an event being handled. + */ + int PROFILE_UPDATED = 2; + + /** + * Propagates the specified event in the context server, notifying + * {@link EventListenerService} instances if needed. If the event is persistent ({@link Event#isPersistent()}, it will be persisted appropriately. Once the event is + * propagated, any {@link ActionPostExecutor} the event defined will be executed and the user profile updated if needed. + * + * @param event the Event to be propagated + * @return the result of the event handling as combination of EventService flags, to be checked using bitwise AND (&) operator + */ + int send(Event event); + + /** + * Retrieves the list of available event properties. + * + * @return a list of available event properties + */ + List<EventProperty> getEventProperties(); + + /** + * Retrieves the set of known event type identifiers. + * + * @return the set of known event type identifiers. + */ + Set<String> getEventTypeIds(); + + /** + * Retrieves {@link Event}s matching the specified {@link Condition}. Events are ordered according to their time stamp ({@link Event#getTimeStamp()} and paged: only + * {@code size} of them are retrieved, starting with the {@code offset}-th one. + * + * @param condition the Condition we want the Events to match to be retrieved + * @param offset zero or a positive integer specifying the position of the first event in the total ordered collection of matching events + * @param size a positive integer specifying how many matching events should be retrieved or {@code -1} if all of them should be retrieved + * @return a {@link PartialList} of matching events + */ + PartialList<Event> searchEvents(Condition condition, int offset, int size); + + /** + * Retrieves {@link Event}s for the {@link Session} identified by the provided session identifier, matching any of the provided event types, + * ordered according to the specified {@code sortBy} String and paged: only {@code size} of them are retrieved, starting with the {@code offset}-th one. + * If a {@code query} is provided, a full text search is performed on the matching events to further filter them. + * + * @param sessionId the identifier of the user session we're considering + * @param eventTypes an array of event type names; the events to retrieve should at least match one of these + * @param query a String to perform full text filtering on events matching the other conditions + * @param offset zero or a positive integer specifying the position of the first event in the total ordered collection of matching events + * @param size a positive integer specifying how many matching events should be retrieved or {@code -1} if all of them should be retrieved + * @param sortBy an optional ({@code null} if no sorting is required) String of comma ({@code ,}) separated property names on which ordering should be performed, ordering elements according to the property order in + * the String, considering each in turn and moving on to the next one in case of equality of all preceding ones. Each property name is optionally followed by + * a column ({@code :}) and an order specifier: {@code asc} or {@code desc}. + * @return a {@link PartialList} of matching events + */ + PartialList<Event> searchEvents(String sessionId, String[] eventTypes, String query, int offset, int size, String sortBy); + + /** + * Checks whether the specified event has already been raised either for the associated session or profile depending on the specified {@code session} parameter. + * + * @param event the event we want to check + * @param session {@code true} if we want to check if the specified event has already been raised for the associated session, {@code false} if we want to check + * whether the event has already been raised for the associated profile + * @return {@code true} if the event has already been raised, {@code false} otherwise + */ + boolean hasEventAlreadyBeenRaised(Event event, boolean session); +} http://git-wip-us.apache.org/repos/asf/incubator-unomi/blob/dc1d1520/api/src/main/java/org/apache/unomi/api/services/GoalsService.java ---------------------------------------------------------------------- diff --git a/api/src/main/java/org/apache/unomi/api/services/GoalsService.java b/api/src/main/java/org/apache/unomi/api/services/GoalsService.java new file mode 100644 index 0000000..08e384e --- /dev/null +++ b/api/src/main/java/org/apache/unomi/api/services/GoalsService.java @@ -0,0 +1,171 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You 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 org.apache.unomi.api.services; + +import org.apache.unomi.api.Metadata; +import org.apache.unomi.api.PartialList; +import org.apache.unomi.api.campaigns.Campaign; +import org.apache.unomi.api.campaigns.CampaignDetail; +import org.apache.unomi.api.campaigns.events.CampaignEvent; +import org.apache.unomi.api.goals.Goal; +import org.apache.unomi.api.goals.GoalReport; +import org.apache.unomi.api.query.AggregateQuery; +import org.apache.unomi.api.query.Query; +import org.apache.unomi.api.rules.Rule; + +import java.util.Set; + +/** + * A service to interact with {@link Goal}s and {@link Campaign}s. + */ +public interface GoalsService { + /** + * Retrieves the set of Metadata associated with existing goals. + * + * @return the set of Metadata associated with existing goals + */ + Set<Metadata> getGoalMetadatas(); + + /** + * Retrieves the set of Metadata associated with existing goals matching the specified {@link Query} + * + * @param query the Query used to filter the Goals which metadata we want to retrieve + * @return the set of Metadata associated with existing goals matching the specified {@link Query} + */ + Set<Metadata> getGoalMetadatas(Query query); + + /** + * Retrieves the goal associated with the specified identifier. + * + * @param goalId the identifier of the goal to retrieve + * @return the goal associated with the specified identifier or {@code null} if no such goal exists + */ + Goal getGoal(String goalId); + + /** + * Saves the specified goal in the context server and creates associated {@link Rule}s if the goal is enabled. + * + * TODO: rename to saveGoal + * + * @param goal the Goal to be saved + */ + void setGoal(Goal goal); + + /** + * Removes the goal associated with the specified identifier, also removing associated rules if needed. + * + * @param goalId the identifier of the goal to be removed + */ + void removeGoal(String goalId); + + /** + * Retrieves the report for the goal identified with the specified identifier. + * + * @param goalId the identifier of the goal which report we want to retrieve + * @return the report for the specified goal + */ + GoalReport getGoalReport(String goalId); + + /** + * Retrieves the report for the goal identified with the specified identifier, considering only elements determined by the specified {@link AggregateQuery}. + * + * @param goalId the identifier of the goal which report we want to retrieve + * @param query an AggregateQuery to further specify which elements of the report we want + * @return the report for the specified goal and query + */ + GoalReport getGoalReport(String goalId, AggregateQuery query); + + /** + * Retrieves the set of Metadata associated with existing campaigns. + * + * @return the set of Metadata associated with existing campaigns + */ + Set<Metadata> getCampaignMetadatas(); + + /** + * Retrieves the set of Metadata associated with existing campaign matching the specified {@link Query} + * + * @param query the Query used to filter the campagins which metadata we want to retrieve + * @return the set of Metadata associated with existing campaigns matching the specified {@link Query} + */ + Set<Metadata> getCampaignMetadatas(Query query); + + /** + * Retrieves campaign details for campaigns matching the specified query. + * + * @param query the query specifying which campaigns to retrieve + * @return a {@link PartialList} of campaign details for the campaigns matching the specified query + */ + PartialList<CampaignDetail> getCampaignDetails(Query query); + + /** + * Retrieves the {@link CampaignDetail} associated with the campaign identified with the specified identifier + * + * @param id the identifier of the campaign for which we want to retrieve the details + * @return the CampaignDetail for the campaign identified by the specified identifier or {@code null} if no such campaign exists + */ + CampaignDetail getCampaignDetail(String id); + + /** + * Retrieves the campaign identified by the specified identifier + * + * @param campaignId the identifier of the campaign we want to retrieve + * @return the campaign associated with the specified identifier or {@code null} if no such campaign exists + */ + Campaign getCampaign(String campaignId); + + /** + * Saves the specified campaign in the context server and creates associated {@link Rule}s if the campaign is enabled. + * + * TODO: rename to saveCampaign + * + * @param campaign the Campaign to be saved + */ + void setCampaign(Campaign campaign); + + /** + * Removes the campaign associated with the specified identifier, also removing associated rules if needed. + * + * @param campaignId the identifier of the campaign to be removed + */ + void removeCampaign(String campaignId); + + /** + * Retrieves {@link CampaignEvent}s matching the specified query. + * + * @param query the Query specifying which CampaignEvents to retrieve + * @return a {@link PartialList} of campaign events matching the specified query + */ + PartialList<CampaignEvent> getEvents(Query query); + + /** + * Saves the specified campaign event in the context server. + * + * TODO: rename to saveCampaignEvent + * + * @param event the CampaignEvent to be saved + */ + void setCampaignEvent(CampaignEvent event); + + /** + * Removes the campaign event associated with the specified identifier. + * + * @param campaignEventId the identifier of the campaign event to be removed + */ + void removeCampaignEvent(String campaignEventId); +} http://git-wip-us.apache.org/repos/asf/incubator-unomi/blob/dc1d1520/api/src/main/java/org/apache/unomi/api/services/PrivacyService.java ---------------------------------------------------------------------- diff --git a/api/src/main/java/org/apache/unomi/api/services/PrivacyService.java b/api/src/main/java/org/apache/unomi/api/services/PrivacyService.java new file mode 100644 index 0000000..999db48 --- /dev/null +++ b/api/src/main/java/org/apache/unomi/api/services/PrivacyService.java @@ -0,0 +1,57 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You 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 org.apache.unomi.api.services; + +import org.apache.unomi.api.ServerInfo; + +import java.util.List; + +/** + * This service regroups all privacy-related operations + */ +public interface PrivacyService { + + String GLOBAL_ANONYMOUS_PROFILE_ID = "global-anonymous-profile"; + + ServerInfo getServerInfo(); + + Boolean deleteProfile(String profileId); + + String anonymizeBrowsingData(String profileId); + + Boolean deleteProfileData(String profileId); + + Boolean setAnonymous(String profileId, boolean anonymous); + + Boolean isAnonymous(String profileId); + + List<String> getFilteredEventTypes(String profileId); + + Boolean setFilteredEventTypes(String profileId, List<String> eventTypes); + + List<String> getDeniedProperties(String profileId); + + Boolean setDeniedProperties(String profileId, List<String> propertyNames); + + List<String> getDeniedPropertyDistribution(String profileId); + + Boolean setDeniedPropertyDistribution(String profileId, List<String> propertyNames); + + Boolean removeProperty(String profileId, String propertyName); + +} http://git-wip-us.apache.org/repos/asf/incubator-unomi/blob/dc1d1520/api/src/main/java/org/apache/unomi/api/services/ProfileService.java ---------------------------------------------------------------------- diff --git a/api/src/main/java/org/apache/unomi/api/services/ProfileService.java b/api/src/main/java/org/apache/unomi/api/services/ProfileService.java new file mode 100644 index 0000000..54a2e0c --- /dev/null +++ b/api/src/main/java/org/apache/unomi/api/services/ProfileService.java @@ -0,0 +1,296 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You 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 org.apache.unomi.api.services; + +import org.apache.unomi.api.*; +import org.apache.unomi.api.conditions.Condition; +import org.apache.unomi.api.query.Query; + +import java.util.*; + +/** + * A service to access and operate on {@link Profile}s, {@link Session}s and {@link Persona}s. + */ +public interface ProfileService { + + /** + * Retrieves the number of unique profiles. + * + * @return the number of unique profiles. + */ + long getAllProfilesCount(); + + /** + * Retrieves profiles or personas matching the specified query. + * + * @param <T> the specific sub-type of {@link Profile} to retrieve + * @param query a {@link Query} specifying which elements to retrieve + * @param clazz the class of elements to retrieve + * @return a {@link PartialList} of {@code T} instances matching the specified query + */ + <T extends Profile> PartialList<T> search(Query query, Class<T> clazz); + + /** + * Creates a String containing comma-separated values (CSV) formatted version of profiles matching the specified query. + * + * @param query the query specifying which profiles to export + * @return a CSV-formatted String version of the profiles matching the specified query + */ + String exportProfilesPropertiesToCsv(Query query); + + /** + * Find profiles which have the specified property with the specified value, ordered according to the specified {@code sortBy} String and paged: only + * {@code size} of them are retrieved, starting with the {@code offset}-th one. + * + * TODO: replace with version using a query instead of separate parameters + * TODO: remove as it's unused? + * + * @param propertyName the name of the property we're interested in + * @param propertyValue the value of the property we want profiles to have + * @param offset zero or a positive integer specifying the position of the first profile in the total ordered collection of matching profiles + * @param size a positive integer specifying how many matching profiles should be retrieved or {@code -1} if all of them should be retrieved + * @param sortBy an optional ({@code null} if no sorting is required) String of comma ({@code ,}) separated property names on which ordering should be performed, ordering elements according to the property order in + * the String, considering each in turn and moving on to the next one in case of equality of all preceding ones. Each property name is optionally + * followed by a column ({@code :}) and an order specifier: {@code asc} or {@code desc}. + * @return a {@link PartialList} of matching profiles + */ + PartialList<Profile> findProfilesByPropertyValue(String propertyName, String propertyValue, int offset, int size, String sortBy); + + /** + * Merges the specified profiles into the provided so-called master profile, merging properties according to the {@link PropertyMergeStrategyType} specified on their {@link + * PropertyType}. + * + * @param masterProfile the profile into which the specified profiles will be merged + * @param profilesToMerge the list of profiles to merge into the specified master profile + * @return the merged profile + */ + Profile mergeProfiles(Profile masterProfile, List<Profile> profilesToMerge); + + /** + * Retrieves the profile identified by the specified identifier. + * + * @param profileId the identifier of the profile to retrieve + * @return the profile identified by the specified identifier or {@code null} if no such profile exists + */ + Profile load(String profileId); + + /** + * Saves the specified profile in the context server. + * + * @param profile the profile to be saved + * @return the newly saved profile + */ + Profile save(Profile profile); + + /** + * Removes the profile (or persona if the {@code persona} parameter is set to {@code true}) identified by the specified identifier. + * + * @param profileId the identifier of the profile or persona to delete + * @param persona {@code true} if the specified identifier is supposed to refer to a persona, {@code false} if it is supposed to refer to a profile + */ + void delete(String profileId, boolean persona); + + /** + * Retrieves the sessions associated with the profile identified by the specified identifier that match the specified query (if specified), ordered according to the specified + * {@code sortBy} String and and paged: only {@code size} of them are retrieved, starting with the {@code offset}-th one. + * + * TODO: use a Query object instead of distinct parameter + * + * @param profileId the identifier of the profile we want to retrieve sessions from + * @param query a String of text used for fulltext filtering which sessions we are interested in or {@code null} (or an empty String) if we want to retrieve all sessions + * @param offset zero or a positive integer specifying the position of the first session in the total ordered collection of matching sessions + * @param size a positive integer specifying how many matching sessions should be retrieved or {@code -1} if all of them should be retrieved + * @param sortBy an optional ({@code null} if no sorting is required) String of comma ({@code ,}) separated property names on which ordering should be performed, ordering elements according to the property order in the + * String, considering each in turn and moving on to the next one in case of equality of all preceding ones. Each property name is optionally followed by + * a column ({@code :}) and an order specifier: {@code asc} or {@code desc}. + * @return a {@link PartialList} of matching sessions + */ + PartialList<Session> getProfileSessions(String profileId, String query, int offset, int size, String sortBy); + + /** + * Retrieves the session identified by the specified identifier. + * + * @param sessionId the identifier of the session to be retrieved + * @param dateHint a Date helping in identifying where the item is located + * @return the session identified by the specified identifier + */ + Session loadSession(String sessionId, Date dateHint); + + /** + * Saves the specified session. + * + * @param session the session to be saved + * @return the newly saved session + */ + Session saveSession(Session session); + + /** + * Retrieves sessions associated with the profile identified by the specified identifier. + * + * @param profileId the profile id for which we want to retrieve the sessions + * @return a {@link PartialList} of the profile's sessions + */ + PartialList<Session> findProfileSessions(String profileId); + + /** + * Checks whether the specified profile and/or session satisfy the specified condition. + * + * @param condition the condition we're testing against which might or might not have profile- or session-specific sub-conditions + * @param profile the profile we're testing + * @param session the session we're testing + * @return {@code true} if the profile and/or sessions match the specified condition, {@code false} otherwise + */ + boolean matchCondition(Condition condition, Profile profile, Session session); + + /** + * Update all profiles in batch according to the specified {@link BatchUpdate} + * + * @param update the batch update specification + */ + void batchProfilesUpdate(BatchUpdate update); + + /** + * Retrieves the persona identified by the specified identifier. + * + * @param personaId the identifier of the persona to retrieve + * @return the persona associated with the specified identifier or {@code null} if no such persona exists. + */ + Persona loadPersona(String personaId); + + /** + * Persists the specified {@link Persona} in the context server. + * + * @param persona the persona to persist + * @return the newly persisted persona + */ + Persona savePersona(Persona persona); + + /** + * Retrieves the persona identified by the specified identifier and all its associated sessions + * + * @param personaId the identifier of the persona to retrieve + * @return a {@link PersonaWithSessions} instance with the persona identified by the specified identifier and all its associated sessions + */ + PersonaWithSessions loadPersonaWithSessions(String personaId); + + /** + * Creates a persona with the specified identifier and automatically creates an associated session with it. + * + * @param personaId the identifier to use for the new persona + * @return the newly created persona + */ + Persona createPersona(String personaId); + + /** + * Retrieves the sessions associated with the persona identified by the specified identifier, ordered according to the specified {@code sortBy} String and and paged: only + * {@code size} of them are retrieved, starting with the {@code offset}-th one. + * + * @param personaId the persona id + * @param offset zero or a positive integer specifying the position of the first session in the total ordered collection of matching sessions + * @param size a positive integer specifying how many matching sessions should be retrieved or {@code -1} if all of them should be retrieved + * @param sortBy an optional ({@code null} if no sorting is required) String of comma ({@code ,}) separated property names on which ordering should be performed, ordering elements according to the property order in the + * String, considering each in turn and moving on to the next one in case of equality of all preceding ones. Each property name is optionally followed by + * a column ({@code :}) and an order specifier: {@code asc} or {@code desc}. + * @return a {@link PartialList} of sessions for the persona identified by the specified identifier + */ + PartialList<Session> getPersonaSessions(String personaId, int offset, int size, String sortBy); + + /** + * Retrieves all the property types associated with the specified target. + * + * TODO: move to a different class + * + * @param target the target for which we want to retrieve the associated property types + * @return a collection of all the property types associated with the specified target + */ + Collection<PropertyType> getAllPropertyTypes(String target); + + /** + * Retrieves all known property types. + * + * TODO: move to a different class + * TODO: use Map instead of HashMap + * + * @return a Map associating targets as keys to related {@link PropertyType}s + */ + HashMap<String, Collection<PropertyType>> getAllPropertyTypes(); + + /** + * Retrieves all property types with the specified tag also retrieving property types with sub-tags of the specified tag if so specified. + * + * TODO: move to a different class + * + * @param tag the tag name marking property types we want to retrieve + * @param includeFromSubtags {@code true} if sub-tags of the specified tag should also be considered, {@code false} otherwise + * @return a Set of the property types with the specified tag + */ + Set<PropertyType> getPropertyTypeByTag(String tag, boolean includeFromSubtags); + + /** + * TODO + */ + String getPropertyTypeMapping(String fromPropertyTypeId); + + /** + * TODO + */ + Collection<PropertyType> getPropertyTypeByMapping(String propertyName); + + /** + * Retrieves the property type identified by the specified identifier. + * + * TODO: move to a different class + * + * @param id the identifier of the property type to retrieve + * @return the property type identified by the specified identifier or {@code null} if no such property type exists + */ + PropertyType getPropertyType(String id); + + /** + * Persists the specified property type in the context server. + * + * TODO: move to a different class + * + * @param property the property type to persist + * @return {@code true} if the property type was properly created, {@code false} otherwise (for example, if the property type already existed + */ + boolean createPropertyType(PropertyType property); + + /** + * Deletes the property type identified by the specified identifier. + * + * TODO: move to a different class + * + * @param propertyId the identifier of the property type to delete + * @return {@code true} if the property type was properly deleted, {@code false} otherwise + */ + boolean deletePropertyType(String propertyId); + + /** + * Retrieves the existing property types for the specified type as defined by the Item subclass public field {@code ITEM_TYPE} and with the specified tag. + * + * TODO: move to a different class + * + * @param tagId the tag we're interested in + * @param itemType the String representation of the item type we want to retrieve the count of, as defined by its class' {@code ITEM_TYPE} field + * @return all property types defined for the specified item type and with the specified tag + */ + Set<PropertyType> getExistingProperties(String tagId, String itemType); + + +} http://git-wip-us.apache.org/repos/asf/incubator-unomi/blob/dc1d1520/api/src/main/java/org/apache/unomi/api/services/QueryService.java ---------------------------------------------------------------------- diff --git a/api/src/main/java/org/apache/unomi/api/services/QueryService.java b/api/src/main/java/org/apache/unomi/api/services/QueryService.java new file mode 100644 index 0000000..2465e65 --- /dev/null +++ b/api/src/main/java/org/apache/unomi/api/services/QueryService.java @@ -0,0 +1,80 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You 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 org.apache.unomi.api.services; + +import org.apache.unomi.api.Item; +import org.apache.unomi.api.conditions.Condition; +import org.apache.unomi.api.query.AggregateQuery; + +import java.util.Map; + +/** + * A service to perform queries. + */ +public interface QueryService { + + /** + * Retrieves the number of items with the specified type as defined by the Item subclass public field {@code ITEM_TYPE} and aggregated by possible values of the specified + * property. + * + * @param itemType the String representation of the item type we want to retrieve the count of, as defined by its class' {@code ITEM_TYPE} field + * @param property the property we're aggregating on, i.e. for each possible value of this property, we are counting how many items of the specified type have that value + * @return a Map associating a specific value of the property to the cardinality of items with that value + * @see Item Item for a discussion of {@code ITEM_TYPE} + */ + Map<String, Long> getAggregate(String itemType, String property); + + /** + * TODO: rework, this method is confusing since it either behaves like {@link #getAggregate(String, String)} if query is null but completely differently if it isn't + * + * Retrieves the number of items with the specified type as defined by the Item subclass public field {@code ITEM_TYPE} and aggregated by possible values of the specified + * property or, if the specified query is not {@code null}, perform that aggregate query. + * + * @param itemType the String representation of the item type we want to retrieve the count of, as defined by its class' {@code ITEM_TYPE} field + * @param property the property we're aggregating on, i.e. for each possible value of this property, we are counting how many items of the specified type have that value + * @param query the {@link AggregateQuery} specifying the aggregation that should be perfomed + * @return a Map associating a specific value of the property to the cardinality of items with that value + * @see Item Item for a discussion of {@code ITEM_TYPE} + */ + Map<String, Long> getAggregate(String itemType, String property, AggregateQuery query); + + /** + * Retrieves the number of items of the specified type as defined by the Item subclass public field {@code ITEM_TYPE} and matching the specified {@link Condition}. + * + * @param condition the condition the items must satisfy + * @param itemType the String representation of the item type we want to retrieve the count of, as defined by its class' {@code ITEM_TYPE} field + * @return the number of items of the specified type + * @see Item Item for a discussion of {@code ITEM_TYPE} + */ + long getQueryCount(String itemType, Condition condition); + + /** + * Retrieves the specified metrics for the specified field of items of the specified type as defined by the Item subclass public field {@code ITEM_TYPE} and matching the + * specified {@link Condition}. + * + * @param condition the condition the items must satisfy + * @param slashConcatenatedMetrics a String specifying which metrics should be computed, separated by a slash ({@code /}) (possible values: {@code sum} for the sum of the + * values, {@code avg} for the average of the values, {@code min} for the minimum value and {@code max} for the maximum value) + * @param property the name of the field for which the metrics should be computed + * @param type the String representation of the item type we want to retrieve the count of, as defined by its class' {@code ITEM_TYPE} field + * @return a Map associating computed metric name as key to its associated value + * @see Item Item for a discussion of {@code ITEM_TYPE} + */ + Map<String, Double> getMetric(String type, String property, String slashConcatenatedMetrics, Condition condition); + +} http://git-wip-us.apache.org/repos/asf/incubator-unomi/blob/dc1d1520/api/src/main/java/org/apache/unomi/api/services/RulesService.java ---------------------------------------------------------------------- diff --git a/api/src/main/java/org/apache/unomi/api/services/RulesService.java b/api/src/main/java/org/apache/unomi/api/services/RulesService.java new file mode 100644 index 0000000..75d1f07 --- /dev/null +++ b/api/src/main/java/org/apache/unomi/api/services/RulesService.java @@ -0,0 +1,79 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You 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 org.apache.unomi.api.services; + +import org.apache.unomi.api.Item; +import org.apache.unomi.api.Metadata; +import org.apache.unomi.api.PartialList; +import org.apache.unomi.api.conditions.Condition; +import org.apache.unomi.api.query.Query; +import org.apache.unomi.api.rules.Rule; + +import java.util.Set; + +/** + * A service to access and operate on {@link Rule}s. + */ +public interface RulesService { + + /** + * Retrieves the metadata for all known rules. + * + * @return the Set of known metadata + */ + Set<Metadata> getRuleMetadatas(); + + /** + * Retrieves rule metadatas for rules matching the specified {@link Query}. + * + * @param query the query the rules which metadata we want to retrieve must match + * @return a {@link PartialList} of rules metadata for the rules matching the specified query + */ + PartialList<Metadata> getRuleMetadatas(Query query); + + /** + * Retrieves the rule identified by the specified identifier. + * + * @param ruleId the identifier of the rule we want to retrieve + * @return the rule identified by the specified identifier or {@code null} if no such rule exists. + */ + Rule getRule(String ruleId); + + /** + * Persists the specified rule to the context server. + * + * @param rule the rule to be persisted + */ + void setRule(Rule rule); + + /** + * Deletes the rule identified by the specified identifier. + * + * @param ruleId the identifier of the rule we want to delete + */ + void removeRule(String ruleId); + + /** + * Retrieves tracked conditions (rules with a condition marked with the {@code trackedCondition} tag and which {@code sourceEventCondition} matches the specified item) for the + * specified item. + * + * @param item the item which tracked conditions we want to retrieve + * @return the Set of tracked conditions for the specified item + */ + Set<Condition> getTrackedConditions(Item item); +} http://git-wip-us.apache.org/repos/asf/incubator-unomi/blob/dc1d1520/api/src/main/java/org/apache/unomi/api/services/SegmentService.java ---------------------------------------------------------------------- diff --git a/api/src/main/java/org/apache/unomi/api/services/SegmentService.java b/api/src/main/java/org/apache/unomi/api/services/SegmentService.java new file mode 100644 index 0000000..8c1db29 --- /dev/null +++ b/api/src/main/java/org/apache/unomi/api/services/SegmentService.java @@ -0,0 +1,206 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You 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 org.apache.unomi.api.services; + +import org.apache.unomi.api.Item; +import org.apache.unomi.api.Metadata; +import org.apache.unomi.api.PartialList; +import org.apache.unomi.api.Profile; +import org.apache.unomi.api.query.Query; +import org.apache.unomi.api.segments.Scoring; +import org.apache.unomi.api.segments.Segment; +import org.apache.unomi.api.segments.SegmentsAndScores; + +import java.util.List; + +/** + * A service to access and operate on {@link Segment}s and {@link Scoring}s + */ +public interface SegmentService { + + /** + * Retrieves segment metadatas, ordered according to the specified {@code sortBy} String and and paged: only {@code size} of them are retrieved, starting with the {@code + * offset}-th one. + * + * @param offset zero or a positive integer specifying the position of the first element in the total ordered collection of matching elements + * @param size a positive integer specifying how many matching elements should be retrieved or {@code -1} if all of them should be retrieved + * @param sortBy an optional ({@code null} if no sorting is required) String of comma ({@code ,}) separated property names on which ordering should be performed, ordering elements according to the property order in the + * String, considering each in turn and moving on to the next one in case of equality of all preceding ones. Each property name is optionally followed by + * a column ({@code :}) and an order specifier: {@code asc} or {@code desc}. + * @return a {@link PartialList} of segment metadata + */ + PartialList<Metadata> getSegmentMetadatas(int offset, int size, String sortBy); + + /** + * Retrieves segment metadatas for segments in the specified scope, ordered according to the specified {@code sortBy} String and and paged: only {@code size} of them are + * retrieved, starting with the {@code offset}-th one. + * + * TODO: remove? + * + * @param scope the scope for which we want to retrieve segment metadata + * @param offset zero or a positive integer specifying the position of the first element in the total ordered collection of matching elements + * @param size a positive integer specifying how many matching elements should be retrieved or {@code -1} if all of them should be retrieved + * @param sortBy an optional ({@code null} if no sorting is required) String of comma ({@code ,}) separated property names on which ordering should be performed, ordering elements according to the property order in the + * String, considering each in turn and moving on to the next one in case of equality of all preceding ones. Each property name is optionally followed by + * a column ({@code :}) and an order specifier: {@code asc} or {@code desc}. + * @return a {@link PartialList} of segment metadata + */ + PartialList<Metadata> getSegmentMetadatas(String scope, int offset, int size, String sortBy); + + /** + * Retrieves the metadata for segments matching the specified {@link Query}. + * + * @param query the query that the segments must match for their metadata to be retrieved + * @return a {@link PartialList} of segment metadata + */ + PartialList<Metadata> getSegmentMetadatas(Query query); + + /** + * Retrieves the segment identified by the specified identifier. + * + * @param segmentId the identifier of the segment to be retrieved + * @return the segment identified by the specified identifier or {@code null} if no such segment exists + */ + Segment getSegmentDefinition(String segmentId); + + /** + * Persists the specified segment in the context server. + * + * @param segment the segment to be persisted + */ + void setSegmentDefinition(Segment segment); + + /** + * Removes the segment definition identified by the specified identifier. We can specify that we want the operation to be validated beforehand so that we can + * know if any other segment that might use the segment we're trying to delete as a condition might be impacted. If {@code validate} is set to {@code false}, no + * validation is performed. If set to {@code true}, we will first check if any segment depends on the one we're trying to delete and if so we will not delete the + * segment but rather return the list of the metadata of the impacted segments. If no dependents are found, then we properly delete the segment. + * + * @param segmentId the identifier of the segment we want to delete + * @param validate whether or not to perform validation + * @return a list of impacted segment metadata if any or an empty list if no such impacted segments are found or validation was skipped + */ + List<Metadata> removeSegmentDefinition(String segmentId, boolean validate); + + /** + * Retrieves the list of segment metadata of segments depending on the segment identified by the specified identifier. A segment is depending on another one if it includes + * that segment as part of its condition for profile matching. + * + * TODO: Rename to something clearer, maybe getDependentSegmentMetadata? + * + * @param segmentId the identifier of the segment which impact we want to evaluate + * @return a list of metadata of segments depending on the specified segment + */ + List<Metadata> getImpactedSegmentMetadata(String segmentId); + + /** + * Retrieves a list of profiles matching the conditions defined by the segment identified by the specified identifier, ordered according to the specified {@code sortBy} + * String and and paged: only {@code size} of them are retrieved, starting with the {@code offset}-th one. + * + * @param segmentID the identifier of the segment for which we want to retrieve matching profiles + * @param offset zero or a positive integer specifying the position of the first element in the total ordered collection of matching elements + * @param size a positive integer specifying how many matching elements should be retrieved or {@code -1} if all of them should be retrieved + * @param sortBy an optional ({@code null} if no sorting is required) String of comma ({@code ,}) separated property names on which ordering should be performed, ordering elements according to the property order in the + * String, considering each in turn and moving on to the next one in case of equality of all preceding ones. Each property name is optionally followed by + * a column ({@code :}) and an order specifier: {@code asc} or {@code desc}. + * @return a {@link PartialList} of profiles matching the specified segment + */ + PartialList<Profile> getMatchingIndividuals(String segmentID, int offset, int size, String sortBy); + + /** + * Retrieves the number of profiles matching the conditions defined by the segment identified by the specified identifier. + * + * @param segmentID the identifier of the segment for which we want to retrieve matching profiles + * @return the number of profiles matching the conditions defined by the segment identified by the specified identifier + */ + long getMatchingIndividualsCount(String segmentID); + + /** + * Determines whether the specified profile is part of the segment identified by the specified identifier. + * + * @param profile the profile we want to check + * @param segmentId the identifier of the segment against which we want to check the profile + * @return {@code true} if the specified profile is in the specified segment, {@code false} otherwise + */ + Boolean isProfileInSegment(Profile profile, String segmentId); + + /** + * Retrieves the segments and scores for the specified profile. + * + * @param profile the profile for which we want to retrieve segments and scores + * @return a {@link SegmentsAndScores} instance encapsulating the segments and scores for the specified profile + */ + SegmentsAndScores getSegmentsAndScoresForProfile(Profile profile); + + /** + * Retrieves the list of segment metadata for the segments the specified profile is a member of. + * + * @param profile the profile for which we want to retrieve the segment metadata + * @return the (possibly empty) list of segment metadata for the segments the specified profile is a member of + */ + List<Metadata> getSegmentMetadatasForProfile(Profile profile); + + /** + * Retrieves the set of all scoring metadata. + * + * @return the set of all scoring metadata + */ + PartialList<Metadata> getScoringMetadatas(int offset, int size, String sortBy); + + /** + * Retrieves the set of scoring metadata for scorings matching the specified query. + * + * @param query the query the scorings must match for their metadata to be retrieved + * @return the set of scoring metadata for scorings matching the specified query + */ + PartialList<Metadata> getScoringMetadatas(Query query); + + /** + * Retrieves the scoring identified by the specified identifier. + * + * @param scoringId the identifier of the scoring to be retrieved + * @return the scoring identified by the specified identifier or {@code null} if no such scoring exists + */ + Scoring getScoringDefinition(String scoringId); + + /** + * Persists the specified scoring in the context server. + * + * @param scoring the scoring to be persisted + */ + void setScoringDefinition(Scoring scoring); + + /** + * Creates a scoring with the specified scope, identifier, name and description. + * + * @param scope the scope for the new scoring + * @param scoringId the identifier for the new scoring + * @param name the name of the new scoring + * @param description the description of the new scoring + * @see Item Item's description for a discussion of scope + */ + void createScoringDefinition(String scope, String scoringId, String name, String description); + + /** + * Deletes the scoring identified by the specified identifier from the context server. + * + * @param scoringId the identifier of the scoring to be deleted + */ + void removeScoringDefinition(String scoringId); + +} http://git-wip-us.apache.org/repos/asf/incubator-unomi/blob/dc1d1520/api/src/main/java/org/oasis_open/contextserver/api/BatchUpdate.java ---------------------------------------------------------------------- diff --git a/api/src/main/java/org/oasis_open/contextserver/api/BatchUpdate.java b/api/src/main/java/org/oasis_open/contextserver/api/BatchUpdate.java deleted file mode 100644 index 4e3e24b..0000000 --- a/api/src/main/java/org/oasis_open/contextserver/api/BatchUpdate.java +++ /dev/null @@ -1,104 +0,0 @@ -/* - * Licensed to the Apache Software Foundation (ASF) under one or more - * contributor license agreements. See the NOTICE file distributed with - * this work for additional information regarding copyright ownership. - * The ASF licenses this file to You 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 org.oasis_open.contextserver.api; - -import org.oasis_open.contextserver.api.conditions.Condition; - -/** - * A representation of an operation to update the value of a property on items matching a specific condition. - */ -public class BatchUpdate { - private String propertyName; - private Object propertyValue; - private Condition condition; - private String strategy; - - /** - * Retrieves the property name which value needs to be updated. Note that the property name follows the - * <a href='https://commons.apache.org/proper/commons-beanutils/apidocs/org/apache/commons/beanutils/expression/DefaultResolver.html'>Apache Commons BeanUtils expression - * format</a> - * - * @return an Apache Commons BeanUtils expression identifying which property we want to update - */ - public String getPropertyName() { - return propertyName; - } - - /** - * Specifies (as an Apache Commons BeanUtils expression) which property needs to be updated. - * - * @param propertyName an Apache Commons BeanUtils expression identifying which property we want to update - */ - public void setPropertyName(String propertyName) { - this.propertyName = propertyName; - } - - /** - * Retrieves the new property value. - * - * @return the new property value - */ - public Object getPropertyValue() { - return propertyValue; - } - - /** - * Sets the new property value to use for the update. - * - * @param propertyValue the new property value to use for the update - */ - public void setPropertyValue(Object propertyValue) { - this.propertyValue = propertyValue; - } - - /** - * Retrieves the condition which items we want to update must satisfy. - * - * @return the condition which items we want to update must satisfy - */ - public Condition getCondition() { - return condition; - } - - /** - * Specifies the condition which items to update. - * - * @param condition the condition specifying which items to update - */ - public void setCondition(Condition condition) { - this.condition = condition; - } - - /** - * Retrieves the identifier for the {@link PropertyMergeStrategyType} to use during the update if needed. - * - * @return the identifier for the {@link PropertyMergeStrategyType} to use during the update if needed - */ - public String getStrategy() { - return strategy; - } - - /** - * Sets the identifier for the {@link PropertyMergeStrategyType} to use during the update if needed. - * - * @param strategy the identifier for the {@link PropertyMergeStrategyType} to use during the update if needed - */ - public void setStrategy(String strategy) { - this.strategy = strategy; - } -} http://git-wip-us.apache.org/repos/asf/incubator-unomi/blob/dc1d1520/api/src/main/java/org/oasis_open/contextserver/api/ClusterNode.java ---------------------------------------------------------------------- diff --git a/api/src/main/java/org/oasis_open/contextserver/api/ClusterNode.java b/api/src/main/java/org/oasis_open/contextserver/api/ClusterNode.java deleted file mode 100644 index 74fe2ba..0000000 --- a/api/src/main/java/org/oasis_open/contextserver/api/ClusterNode.java +++ /dev/null @@ -1,225 +0,0 @@ -/* - * Licensed to the Apache Software Foundation (ASF) under one or more - * contributor license agreements. See the NOTICE file distributed with - * this work for additional information regarding copyright ownership. - * The ASF licenses this file to You 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 org.oasis_open.contextserver.api; - -import java.io.Serializable; - -/** - * Information about a cluster node. - */ -public class ClusterNode implements Serializable { - - private static final long serialVersionUID = 1281422346318230514L; - - private double cpuLoad; - private double[] loadAverage; - private String hostName; - private String hostAddress; - private int publicPort; - private String secureHostAddress; - private int securePort; - private long uptime; - private boolean master; - private boolean data; - - /** - * Instantiates a new Cluster node. - */ - public ClusterNode() { - } - - /** - * Retrieves the cpu load. - * - * @return the cpu load - */ - public double getCpuLoad() { - return cpuLoad; - } - - /** - * Sets the cpu load. - * - * @param cpuLoad the cpu load - */ - public void setCpuLoad(double cpuLoad) { - this.cpuLoad = cpuLoad; - } - - /** - * Retrieves the host name. - * - * @return the host name - */ - public String getHostName() { - return hostName; - } - - /** - * Sets the host name. - * - * @param hostName the host name - */ - public void setHostName(String hostName) { - this.hostName = hostName; - } - - /** - * Retrieves the host address. - * - * @return the host address - */ - public String getHostAddress() { - return hostAddress; - } - - /** - * Sets the host address. - * - * @param hostAddress the host address - */ - public void setHostAddress(String hostAddress) { - this.hostAddress = hostAddress; - } - - /** - * Retrieves the public port. - * - * @return the public port - */ - public int getPublicPort() { - return publicPort; - } - - /** - * Sets the public port. - * - * @param publicPort the public port - */ - public void setPublicPort(int publicPort) { - this.publicPort = publicPort; - } - - /** - * Retrieves the secure host address which uses the HTTPS protocol for communications between clients and the context server. - * - * @return the secure host address - */ - public String getSecureHostAddress() { - return secureHostAddress; - } - - /** - * Sets the secure host address which uses the HTTPS protocol for communications between clients and the context server. - * - * @param secureHostAddress the secure host address - */ - public void setSecureHostAddress(String secureHostAddress) { - this.secureHostAddress = secureHostAddress; - } - - /** - * Retrieves the secure port. - * - * @return the secure port - */ - public int getSecurePort() { - return securePort; - } - - /** - * Sets the secure port. - * - * @param securePort the secure port - */ - public void setSecurePort(int securePort) { - this.securePort = securePort; - } - - /** - * Retrieves the load average for the last minute, five minutes and fifteen minutes. - * - * @return an array of {@code double} containing, in order and starting from index {@code 0}, the load average for the last minute, last five minutes and last fifteen minutes - */ - public double[] getLoadAverage() { - return loadAverage; - } - - /** - * Sets the load average for the last minute, five minutes and fifteen minutes. - * - * @param loadAverage an array of {@code double} containing, in order and starting from index {@code 0}, the load average for the last minute, last five minutes and last fifteen minutes - */ - public void setLoadAverage(double[] loadAverage) { - this.loadAverage = loadAverage; - } - - /** - * Retrieves the uptime. - * - * @return the uptime - */ - public long getUptime() { - return uptime; - } - - /** - * Sets the uptime. - * - * @param uptime the uptime - */ - public void setUptime(long uptime) { - this.uptime = uptime; - } - - /** - * Determines whether this ClusterNode is a master node, i.e. this node doesn't store any data but is only focused on cluster management operations. - * - * @return {@code true} if this node is a master node, {@code false} otherwise - */ - public boolean isMaster() { - return master; - } - - /** - * Specifies whether this ClusterNode is a master node, i.e. this node doesn't store any data but is only focused on cluster management operations.. - * - * @param master {@code true} if this node is a master node, {@code false} otherwise - */ - public void setMaster(boolean master) { - this.master = master; - } - - /** - * Determines whether this ClusterNode locally stores data. - * - * @return {@code true} if this node locally stores data, {@code false} otherwise - */ - public boolean isData() { - return data; - } - - /** - * Specifies whether this ClusterNode locally stores data. - * - * @param data {@code true} if this node locally stores data, {@code false} otherwise - */ - public void setData(boolean data) { - this.data = data; - } -} http://git-wip-us.apache.org/repos/asf/incubator-unomi/blob/dc1d1520/api/src/main/java/org/oasis_open/contextserver/api/ContextRequest.java ---------------------------------------------------------------------- diff --git a/api/src/main/java/org/oasis_open/contextserver/api/ContextRequest.java b/api/src/main/java/org/oasis_open/contextserver/api/ContextRequest.java deleted file mode 100644 index d899be7..0000000 --- a/api/src/main/java/org/oasis_open/contextserver/api/ContextRequest.java +++ /dev/null @@ -1,364 +0,0 @@ -/* - * Licensed to the Apache Software Foundation (ASF) under one or more - * contributor license agreements. See the NOTICE file distributed with - * this work for additional information regarding copyright ownership. - * The ASF licenses this file to You 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 org.oasis_open.contextserver.api; - -import org.oasis_open.contextserver.api.conditions.Condition; - -import java.util.List; -import java.util.Map; -import java.util.Set; - -/** - * An incoming request for context information from clients of the context server. This allows clients to specify which type of information they are interested in getting from - * the context server as well as specify incoming events or content filtering or property/segment overrides for personalization or impersonation. This conditions what the - * context server will return with its response. - * <p/> - * Events that are generated on the client as part of its functioning can be specified in the client as part of its request for contextual data. The context server will deliver - * these events to {@link org.oasis_open.contextserver.api.services.EventListenerService}s to be processed. In particular, the {@link - * org.oasis_open.contextserver.api.services.RulesService} will trigger any applicable {@link org.oasis_open.contextserver.api.rules.Rule} which in turn might trigger {@link - * org.oasis_open.contextserver.api.actions.Action}s. An appropriate Event is also triggered when a Rule matches so that other rules can react to it. Finally, an event will also - * be emitted if the user {@link Profile} has been updated as part of the event processing. - * <p/> - * A client wishing to perform content personalization might also specify filtering condition to be evaluated by the context server so that it can tell the client - * whether the content associated with the filter should be activated for this profile/session. - * <p/> - * It is also possible to clients wishing to perform user impersonation to specify properties or segment to override the proper ones so as to emulate a specific profile, in - * which case the overridden value will temporarily replace the proper values so that all rules will be evaluated with these values instead of the proper ones. - * - * @see ContextResponse - * @see Event - */ -public class ContextRequest { - - private Item source; - private boolean requireSegments; - private List<String> requiredProfileProperties; - private List<String> requiredSessionProperties; - private List<Event> events; - private List<FilteredContent> filters; - - // the following overrides make it possible to override temporarily the current profile segments, properties or - // even session properties. This is useful for building UIs to temporarily override one of these parameters to - // test different filter results. - - private Set<String> segmentOverrides; - private Map<String, Object> profilePropertiesOverrides; - private Map<String, Object> sessionPropertiesOverrides; - - /** - * Retrieves the source of the context request. - * - * @return the source - */ - public Item getSource() { - return source; - } - - /** - * Sets the source. - * - * @param source the source - */ - public void setSource(Item source) { - this.source = source; - } - - /** - * Determines whether or not the context server should return the segments associated with the profile from which the request was issued. - * - * @return {@code true} if the context server should return the profile segments, {@code false otherwise} - * @see ContextResponse#getProfileSegments() - */ - public boolean isRequireSegments() { - return requireSegments; - } - - /** - * Specifies whether to return the profile segments with the response. - * - * @param requireSegments {@code true} if the context server should return the profile segments, {@code false otherwise} - */ - public void setRequireSegments(boolean requireSegments) { - this.requireSegments = requireSegments; - } - - /** - * Retrieves the list of profile properties the context server should return with its context response. - * - * @return the required profile properties the client requested to be returned with the response - * @see ContextResponse#getProfileProperties() - */ - public List<String> getRequiredProfileProperties() { - return requiredProfileProperties; - } - - /** - * Specifies which profile properties should be returned with the response. - * - * @param requiredProfileProperties the profile properties that should be returned with the response - */ - public void setRequiredProfileProperties(List<String> requiredProfileProperties) { - this.requiredProfileProperties = requiredProfileProperties; - } - - /** - * Retrieves the list of session properties the context server should return with its context response. - * - * @return the required session properties the client requested to be returned with the response - * @see ContextResponse#getSessionProperties() - */ - public List<String> getRequiredSessionProperties() { - return requiredSessionProperties; - } - - /** - * Specifies which session properties should be returned with the response. - * - * @param requiredSessionProperties the session properties that should be returned with the response - */ - public void setRequiredSessionProperties(List<String> requiredSessionProperties) { - this.requiredSessionProperties = requiredSessionProperties; - } - - /** - * Retrieves the filters aimed at content personalization that should be evaluated for the given session and/or profile so that the context server can tell the client - * whether the content associated with the filter should be activated for this profile/session. The filter identifier is used in the {@link ContextResponse} with the - * associated evaluation result. - * - * @return the filters aimed at content personalization that should be evaluated for the given session and/or profile - * @see org.oasis_open.contextserver.api.services.ProfileService#matchCondition(Condition, Profile, Session) Details on how the filter conditions are evaluated - * @see ContextResponse#getFilteringResults() Details on how the evaluation results are returned to the client - */ - public List<FilteredContent> getFilters() { - return filters; - } - - /** - * Specifies the content filters to be evaluated. - * - * @param filters the content filters to be evaluated - */ - public void setFilters(List<FilteredContent> filters) { - this.filters = filters; - } - - /** - * Retrieves the events that the client has generated as part of its processes and wishes the context server to process. - * - * @return the client events to be processed by the context server - * @see Event - */ - public List<Event> getEvents() { - return events; - } - - /** - * Specifies the events to be processed by the context server. - * - * @param events the events to be processed by the context server - */ - public void setEvents(List<Event> events) { - this.events = events; - } - - /** - * Retrieves the segment overrides. - * - * @return the segment overrides - */ - public Set<String> getSegmentOverrides() { - return segmentOverrides; - } - - /** - * Sets the segment overrides. - * - * @param segmentOverrides the segment overrides - */ - public void setSegmentOverrides(Set<String> segmentOverrides) { - this.segmentOverrides = segmentOverrides; - } - - /** - * Retrieves the profile properties overrides. - * - * @return the profile properties overrides - */ - public Map<String, Object> getProfilePropertiesOverrides() { - return profilePropertiesOverrides; - } - - /** - * Sets the profile properties overrides. - * - * @param profilePropertiesOverrides the profile properties overrides - */ - public void setProfilePropertiesOverrides(Map<String, Object> profilePropertiesOverrides) { - this.profilePropertiesOverrides = profilePropertiesOverrides; - } - - /** - * Retrieves the session properties overrides. - * - * @return the session properties overrides - */ - public Map<String, Object> getSessionPropertiesOverrides() { - return sessionPropertiesOverrides; - } - - /** - * Sets the session properties overrides. - * - * @param sessionPropertiesOverrides the session properties overrides - */ - public void setSessionPropertiesOverrides(Map<String, Object> sessionPropertiesOverrides) { - this.sessionPropertiesOverrides = sessionPropertiesOverrides; - } - - /** - * A content filtering definition. - */ - public static class FilteredContent { - private String filterid; - private List<Filter> filters; - - /** - * Retrieves the filter identifier associated with this content filtering definition. - * - * @return the filter identifier associated with this content filtering definition - */ - public String getFilterid() { - return filterid; - } - - /** - * Sets the filter identifier associated with this content filtering definition. - * - * @param filterid the filter identifier associated with this content filtering definition - */ - public void setFilterid(String filterid) { - this.filterid = filterid; - } - - /** - * Retrieves the filters. - * - * @return the filters - */ - public List<Filter> getFilters() { - return filters; - } - - /** - * Sets the filters. - * - * @param filters the filters - */ - public void setFilters(List<Filter> filters) { - this.filters = filters; - } - } - - /** - * A filter definition for content filtering - */ - public static class Filter { - private List<Target> appliesOn; - private Condition condition; - - /** - * Retrieves the list of targets this filter applies on. - * - * @return the applies on - */ - public List<Target> getAppliesOn() { - return appliesOn; - } - - /** - * Specifies which targets this filter applies on. - * - * @param appliesOn the list of {@link org.oasis_open.contextserver.api.ContextRequest.Target} this filter should be applied on - */ - public void setAppliesOn(List<Target> appliesOn) { - this.appliesOn = appliesOn; - } - - /** - * Retrieves the condition associated with this filter. - * - * @return the condition associated with this filter - */ - public Condition getCondition() { - return condition; - } - - /** - * Sets the condition associated with this filter. - * - * @param condition the condition associated with this filter - */ - public void setCondition(Condition condition) { - this.condition = condition; - } - } - - /** - * A target for content filtering. - */ - public static class Target { - private String target; - private List<String> values; - - /** - * Retrieves the target. - * - * @return the target - */ - public String getTarget() { - return target; - } - - /** - * Sets the target. - * - * @param target the target - */ - public void setTarget(String target) { - this.target = target; - } - - /** - * Retrieves the values. - * - * @return the values - */ - public List<String> getValues() { - return values; - } - - /** - * Sets the values. - * - * @param values the values - */ - public void setValues(List<String> values) { - this.values = values; - } - } -} http://git-wip-us.apache.org/repos/asf/incubator-unomi/blob/dc1d1520/api/src/main/java/org/oasis_open/contextserver/api/ContextResponse.java ---------------------------------------------------------------------- diff --git a/api/src/main/java/org/oasis_open/contextserver/api/ContextResponse.java b/api/src/main/java/org/oasis_open/contextserver/api/ContextResponse.java deleted file mode 100644 index 7fe1fd4..0000000 --- a/api/src/main/java/org/oasis_open/contextserver/api/ContextResponse.java +++ /dev/null @@ -1,187 +0,0 @@ -/* - * Licensed to the Apache Software Foundation (ASF) under one or more - * contributor license agreements. See the NOTICE file distributed with - * this work for additional information regarding copyright ownership. - * The ASF licenses this file to You 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 org.oasis_open.contextserver.api; - -import org.oasis_open.contextserver.api.conditions.Condition; - -import java.io.Serializable; -import java.util.Map; -import java.util.Set; - -/** - * A context server response resulting from the evaluation of a client's context request. Note that all returned values result of the evaluation of the data provided in the - * associated ContextRequest and might therefore reflect results due to user impersonation via properties / segment overrides. - * - * @see ContextRequest - */ -public class ContextResponse implements Serializable { - - private static final long serialVersionUID = -5638595408986826332L; - - private String profileId; - - private String sessionId; - - private Map<String, Object> profileProperties; - - private Map<String, Object> sessionProperties; - - private Set<String> profileSegments; - - private Map<String, Boolean> filteringResults; - - private Set<Condition> trackedConditions; - - /** - * Retrieves the profile identifier associated with the profile of the user on behalf of which the client performed the context request. - * - * @return the profile identifier associated with the profile of the active user - */ - public String getProfileId() { - return profileId; - } - - /** - * Sets the profile id. - * - * @param profileId the profile id - */ - public void setProfileId(String profileId) { - this.profileId = profileId; - } - - /** - * Retrieves the session identifier associated with the processed request. - * - * @return the session identifier associated with the processed request - * @see Session - */ - public String getSessionId() { - return sessionId; - } - - /** - * Sets the session id. - * - * @param sessionId the session id - */ - public void setSessionId(String sessionId) { - this.sessionId = sessionId; - } - - /** - * Retrieves the profile properties that were requested by the client. - * - * @return the profile properties that were requested by the client - * @see ContextRequest#getRequiredProfileProperties() - */ - public Map<String, Object> getProfileProperties() { - return profileProperties; - } - - /** - * Sets the profile properties. - * - * @param profileProperties the profile properties - */ - public void setProfileProperties(Map<String, Object> profileProperties) { - this.profileProperties = profileProperties; - } - - /** - * Retrieves the session properties that were requested by the client. - * - * @return the session properties that were requested by the client - * @see ContextRequest#getRequiredSessionProperties() - */ - public Map<String, Object> getSessionProperties() { - return sessionProperties; - } - - /** - * Sets the session properties. - * - * @param sessionProperties the session properties - */ - public void setSessionProperties(Map<String, Object> sessionProperties) { - this.sessionProperties = sessionProperties; - } - - /** - * Retrieves the identifiers of the profile segments associated with the user if they were requested by the client. Note that these segments are evaluated taking potential - * overrides as requested by the client or as a result of evaluating overridden properties. - * - * @return the profile segments associated with the user accounting for potential overrides - */ - public Set<String> getProfileSegments() { - return profileSegments; - } - - /** - * Sets the profile segments. - * - * @param profileSegments the profile segments - */ - public void setProfileSegments(Set<String> profileSegments) { - this.profileSegments = profileSegments; - } - - /** - * Retrieves the results of the evaluation content filtering definitions and whether individual definitions match with the associated profile (potentially modified by - * overridden values). - * - * @return a Map associating the filter identifier as key to its evaluation result by the context server - */ - public Map<String, Boolean> getFilteringResults() { - return filteringResults; - } - - /** - * Sets the filtering results. - * - * @param filteringResults the filtering results - */ - public void setFilteringResults(Map<String, Boolean> filteringResults) { - this.filteringResults = filteringResults; - } - - /** - * Retrieves the tracked conditions, if any, associated with the source of the context request that resulted in this ContextResponse. Upon evaluating the incoming request, - * the context server will determine if there are any rules marked with the "trackedCondition" tag and which source condition matches the source of the incoming request and - * return these tracked conditions to the client that can use them to know that the context server can react to events matching the tracked condition and coming from that - * source. This is, in particular, used to implement form mapping (a solution that allows clients to update user profiles based on values provided when a form is submitted). - * - * TODO: trackedCondition should be a constant, possibly on the Tag class? - * - * @return the tracked conditions - * @see ContextRequest#getSource() - * @see org.oasis_open.contextserver.api.services.RulesService#getTrackedConditions(Item) - */ - public Set<Condition> getTrackedConditions() { - return trackedConditions; - } - - /** - * Sets the tracked conditions. - * - * @param trackedConditions the tracked conditions - */ - public void setTrackedConditions(Set<Condition> trackedConditions) { - this.trackedConditions = trackedConditions; - } -} http://git-wip-us.apache.org/repos/asf/incubator-unomi/blob/dc1d1520/api/src/main/java/org/oasis_open/contextserver/api/CustomItem.java ---------------------------------------------------------------------- diff --git a/api/src/main/java/org/oasis_open/contextserver/api/CustomItem.java b/api/src/main/java/org/oasis_open/contextserver/api/CustomItem.java deleted file mode 100644 index 55926b3..0000000 --- a/api/src/main/java/org/oasis_open/contextserver/api/CustomItem.java +++ /dev/null @@ -1,71 +0,0 @@ -/* - * Licensed to the Apache Software Foundation (ASF) under one or more - * contributor license agreements. See the NOTICE file distributed with - * this work for additional information regarding copyright ownership. - * The ASF licenses this file to You 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 org.oasis_open.contextserver.api; - -import java.util.HashMap; -import java.util.Map; - -/** - * A generic extension of Item for context server extensions, properties are stored in a Map. - */ -public class CustomItem extends Item { - private static final long serialVersionUID = -7178914125308851922L; - - /** - * The CustomItem ITEM_TYPE. - * @see Item for a discussion of ITEM_TYPE - */ - public static final String ITEM_TYPE = "custom"; - - private Map<String,Object> properties = new HashMap<String,Object>(); - - /** - * Instantiates a new Custom item. - */ - public CustomItem() { - } - - /** - * Instantiates a new Custom item. - * - * @param itemId the item id - * @param itemType the item type - */ - public CustomItem(String itemId, String itemType) { - super(itemId); - this.itemType = itemType; - } - - /** - * Retrieves this CustomItem's properties. - * - * @return a Map of the item's properties associating the property name as key to its value. - */ - public Map<String, Object> getProperties() { - return properties; - } - - /** - * Sets the properties. - * - * @param properties the properties - */ - public void setProperties(Map<String, Object> properties) { - this.properties = properties; - } -}
