001 /** 002 * Copyright (c) 2000-present Liferay, Inc. All rights reserved. 003 * 004 * This library is free software; you can redistribute it and/or modify it under 005 * the terms of the GNU Lesser General Public License as published by the Free 006 * Software Foundation; either version 2.1 of the License, or (at your option) 007 * any later version. 008 * 009 * This library is distributed in the hope that it will be useful, but WITHOUT 010 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS 011 * FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more 012 * details. 013 */ 014 015 package com.liferay.social.kernel.service; 016 017 import aQute.bnd.annotation.ProviderType; 018 019 import com.liferay.asset.kernel.model.AssetEntry; 020 021 import com.liferay.portal.kernel.dao.orm.ActionableDynamicQuery; 022 import com.liferay.portal.kernel.dao.orm.DynamicQuery; 023 import com.liferay.portal.kernel.dao.orm.IndexableActionableDynamicQuery; 024 import com.liferay.portal.kernel.dao.orm.Projection; 025 import com.liferay.portal.kernel.exception.PortalException; 026 import com.liferay.portal.kernel.exception.SystemException; 027 import com.liferay.portal.kernel.model.PersistedModel; 028 import com.liferay.portal.kernel.search.Indexable; 029 import com.liferay.portal.kernel.search.IndexableType; 030 import com.liferay.portal.kernel.service.BaseLocalService; 031 import com.liferay.portal.kernel.service.PersistedModelLocalService; 032 import com.liferay.portal.kernel.transaction.Isolation; 033 import com.liferay.portal.kernel.transaction.Propagation; 034 import com.liferay.portal.kernel.transaction.Transactional; 035 import com.liferay.portal.kernel.util.OrderByComparator; 036 import com.liferay.portal.kernel.util.Tuple; 037 038 import com.liferay.social.kernel.model.SocialActivity; 039 import com.liferay.social.kernel.model.SocialActivityCounter; 040 041 import java.io.Serializable; 042 043 import java.util.List; 044 045 /** 046 * Provides the local service interface for SocialActivityCounter. Methods of this 047 * service will not have security checks based on the propagated JAAS 048 * credentials because this service can only be accessed from within the same 049 * VM. 050 * 051 * @author Brian Wing Shun Chan 052 * @see SocialActivityCounterLocalServiceUtil 053 * @see com.liferay.portlet.social.service.base.SocialActivityCounterLocalServiceBaseImpl 054 * @see com.liferay.portlet.social.service.impl.SocialActivityCounterLocalServiceImpl 055 * @generated 056 */ 057 @ProviderType 058 @Transactional(isolation = Isolation.PORTAL, rollbackFor = { 059 PortalException.class, SystemException.class}) 060 public interface SocialActivityCounterLocalService extends BaseLocalService, 061 PersistedModelLocalService { 062 /* 063 * NOTE FOR DEVELOPERS: 064 * 065 * Never modify or reference this interface directly. Always use {@link SocialActivityCounterLocalServiceUtil} to access the social activity counter local service. Add custom service methods to {@link com.liferay.portlet.social.service.impl.SocialActivityCounterLocalServiceImpl} and rerun ServiceBuilder to automatically copy the method declarations to this interface. 066 */ 067 068 /** 069 * Adds an activity counter specifying a previous activity and period 070 * length. 071 * 072 * <p> 073 * This method uses the lock service to guard against multiple threads 074 * trying to insert the same counter because this service is called 075 * asynchronously from the social activity service. 076 * </p> 077 * 078 * @param groupId the primary key of the group 079 * @param classNameId the primary key of the entity's class this counter 080 belongs to 081 * @param classPK the primary key of the entity this counter belongs to 082 * @param name the counter name 083 * @param ownerType the counter's owner type. Acceptable values are 084 <code>TYPE_ACTOR</code>, <code>TYPE_ASSET</code> and 085 <code>TYPE_CREATOR</code> defined in {@link 086 SocialActivityCounterConstants}. 087 * @param totalValue the counter's total value (optionally <code>0</code>) 088 * @param previousActivityCounterId the primary key of the activity counter 089 for the previous time period (optionally <code>0</code>, if this 090 is the first) 091 * @param periodLength the period length in days, 092 <code>PERIOD_LENGTH_INFINITE</code> for never ending counters or 093 <code>PERIOD_LENGTH_SYSTEM</code> for the period length defined 094 in <code>portal-ext.properties</code>. For more information see 095 {@link SocialActivityCounterConstants}. 096 * @return the added activity counter 097 */ 098 @Transactional(propagation = Propagation.REQUIRES_NEW) 099 public SocialActivityCounter addActivityCounter(long groupId, 100 long classNameId, long classPK, java.lang.String name, int ownerType, 101 int totalValue, long previousActivityCounterId, int periodLength) 102 throws PortalException; 103 104 /** 105 * Adds or increments activity counters related to an activity. 106 * 107 * </p> 108 * This method is called asynchronously from the social activity service 109 * when the user performs an activity defined in 110 * </code>liferay-social.xml</code>. 111 * </p> 112 * 113 * <p> 114 * This method first calls the activity processor class, if there is one 115 * defined for the activity, checks for limits and increments all the 116 * counters that belong to the activity. Afterwards, it processes the 117 * activity with respect to achievement classes, if any. Lastly it 118 * increments the built-in <code>user.activities</code> and 119 * <code>asset.activities</code> counters. 120 * </p> 121 * 122 * @param activity the social activity 123 */ 124 public void addActivityCounters(SocialActivity activity) 125 throws PortalException; 126 127 /** 128 * Adds the social activity counter to the database. Also notifies the appropriate model listeners. 129 * 130 * @param socialActivityCounter the social activity counter 131 * @return the social activity counter that was added 132 */ 133 @Indexable(type = IndexableType.REINDEX) 134 public SocialActivityCounter addSocialActivityCounter( 135 SocialActivityCounter socialActivityCounter); 136 137 /** 138 * Creates a new social activity counter with the primary key. Does not add the social activity counter to the database. 139 * 140 * @param activityCounterId the primary key for the new social activity counter 141 * @return the new social activity counter 142 */ 143 public SocialActivityCounter createSocialActivityCounter( 144 long activityCounterId); 145 146 /** 147 * Deletes all activity counters, limits, and settings related to the asset. 148 * 149 * <p> 150 * This method subtracts the asset's popularity from the owner's 151 * contribution points. It also creates a new contribution period if the 152 * latest one does not belong to the current period. 153 * </p> 154 * 155 * @param assetEntry the asset entry 156 */ 157 public void deleteActivityCounters(AssetEntry assetEntry) 158 throws PortalException; 159 160 /** 161 * Deletes all activity counters for the entity identified by the class name 162 * and class primary key. 163 * 164 * @param className the entity's class name 165 * @param classPK the primary key of the entity 166 */ 167 public void deleteActivityCounters(java.lang.String className, long classPK) 168 throws PortalException; 169 170 /** 171 * Deletes all activity counters, limits, and settings related to the entity 172 * identified by the class name ID and class primary key. 173 * 174 * @param classNameId the primary key of the entity's class 175 * @param classPK the primary key of the entity 176 */ 177 public void deleteActivityCounters(long classNameId, long classPK) 178 throws PortalException; 179 180 /** 181 * @throws PortalException 182 */ 183 @Override 184 public PersistedModel deletePersistedModel(PersistedModel persistedModel) 185 throws PortalException; 186 187 /** 188 * Deletes the social activity counter with the primary key from the database. Also notifies the appropriate model listeners. 189 * 190 * @param activityCounterId the primary key of the social activity counter 191 * @return the social activity counter that was removed 192 * @throws PortalException if a social activity counter with the primary key could not be found 193 */ 194 @Indexable(type = IndexableType.DELETE) 195 public SocialActivityCounter deleteSocialActivityCounter( 196 long activityCounterId) throws PortalException; 197 198 /** 199 * Deletes the social activity counter from the database. Also notifies the appropriate model listeners. 200 * 201 * @param socialActivityCounter the social activity counter 202 * @return the social activity counter that was removed 203 */ 204 @Indexable(type = IndexableType.DELETE) 205 public SocialActivityCounter deleteSocialActivityCounter( 206 SocialActivityCounter socialActivityCounter); 207 208 /** 209 * Disables all the counters of an asset identified by the class name and 210 * class primary key. 211 * 212 * <p> 213 * This method is used by the recycle bin to disable all counters of assets 214 * put into the recycle bin. It adjusts the owner's contribution score. 215 * </p> 216 * 217 * @param className the asset's class name 218 * @param classPK the primary key of the asset 219 */ 220 public void disableActivityCounters(java.lang.String className, long classPK) 221 throws PortalException; 222 223 /** 224 * Disables all the counters of an asset identified by the class name ID and 225 * class primary key. 226 * 227 * <p> 228 * This method is used by the recycle bin to disable all counters of assets 229 * put into the recycle bin. It adjusts the owner's contribution score. 230 * </p> 231 * 232 * @param classNameId the primary key of the asset's class 233 * @param classPK the primary key of the asset 234 */ 235 public void disableActivityCounters(long classNameId, long classPK) 236 throws PortalException; 237 238 public DynamicQuery dynamicQuery(); 239 240 /** 241 * Performs a dynamic query on the database and returns the matching rows. 242 * 243 * @param dynamicQuery the dynamic query 244 * @return the matching rows 245 */ 246 public <T> List<T> dynamicQuery(DynamicQuery dynamicQuery); 247 248 /** 249 * Performs a dynamic query on the database and returns a range of the matching rows. 250 * 251 * <p> 252 * Useful when paginating results. Returns a maximum of <code>end - start</code> instances. <code>start</code> and <code>end</code> are not primary keys, they are indexes in the result set. Thus, <code>0</code> refers to the first result in the set. Setting both <code>start</code> and <code>end</code> to {@link com.liferay.portal.kernel.dao.orm.QueryUtil#ALL_POS} will return the full result set. If <code>orderByComparator</code> is specified, then the query will include the given ORDER BY logic. If <code>orderByComparator</code> is absent and pagination is required (<code>start</code> and <code>end</code> are not {@link com.liferay.portal.kernel.dao.orm.QueryUtil#ALL_POS}), then the query will include the default ORDER BY logic from {@link com.liferay.portlet.social.model.impl.SocialActivityCounterModelImpl}. If both <code>orderByComparator</code> and pagination are absent, for performance reasons, the query will not have an ORDER BY clause and the returned result set will be sorted on by the primary key in an ascending order. 253 * </p> 254 * 255 * @param dynamicQuery the dynamic query 256 * @param start the lower bound of the range of model instances 257 * @param end the upper bound of the range of model instances (not inclusive) 258 * @return the range of matching rows 259 */ 260 public <T> List<T> dynamicQuery(DynamicQuery dynamicQuery, int start, 261 int end); 262 263 /** 264 * Performs a dynamic query on the database and returns an ordered range of the matching rows. 265 * 266 * <p> 267 * Useful when paginating results. Returns a maximum of <code>end - start</code> instances. <code>start</code> and <code>end</code> are not primary keys, they are indexes in the result set. Thus, <code>0</code> refers to the first result in the set. Setting both <code>start</code> and <code>end</code> to {@link com.liferay.portal.kernel.dao.orm.QueryUtil#ALL_POS} will return the full result set. If <code>orderByComparator</code> is specified, then the query will include the given ORDER BY logic. If <code>orderByComparator</code> is absent and pagination is required (<code>start</code> and <code>end</code> are not {@link com.liferay.portal.kernel.dao.orm.QueryUtil#ALL_POS}), then the query will include the default ORDER BY logic from {@link com.liferay.portlet.social.model.impl.SocialActivityCounterModelImpl}. If both <code>orderByComparator</code> and pagination are absent, for performance reasons, the query will not have an ORDER BY clause and the returned result set will be sorted on by the primary key in an ascending order. 268 * </p> 269 * 270 * @param dynamicQuery the dynamic query 271 * @param start the lower bound of the range of model instances 272 * @param end the upper bound of the range of model instances (not inclusive) 273 * @param orderByComparator the comparator to order the results by (optionally <code>null</code>) 274 * @return the ordered range of matching rows 275 */ 276 public <T> List<T> dynamicQuery(DynamicQuery dynamicQuery, int start, 277 int end, OrderByComparator<T> orderByComparator); 278 279 /** 280 * Returns the number of rows matching the dynamic query. 281 * 282 * @param dynamicQuery the dynamic query 283 * @return the number of rows matching the dynamic query 284 */ 285 public long dynamicQueryCount(DynamicQuery dynamicQuery); 286 287 /** 288 * Returns the number of rows matching the dynamic query. 289 * 290 * @param dynamicQuery the dynamic query 291 * @param projection the projection to apply to the query 292 * @return the number of rows matching the dynamic query 293 */ 294 public long dynamicQueryCount(DynamicQuery dynamicQuery, 295 Projection projection); 296 297 /** 298 * Enables all the counters of an asset identified by the class name and 299 * class primary key. 300 * 301 * <p> 302 * This method is used by the recycle bin to enable all counters of assets 303 * restored from the recycle bin. It adjusts the owner's contribution score. 304 * </p> 305 * 306 * @param className the asset's class name 307 * @param classPK the primary key of the asset 308 */ 309 public void enableActivityCounters(java.lang.String className, long classPK) 310 throws PortalException; 311 312 /** 313 * Enables all activity counters of an asset identified by the class name ID 314 * and class primary key. 315 * 316 * <p> 317 * This method is used by the recycle bin to enable all counters of assets 318 * restored from the recycle bin. It adjusts the owner's contribution score. 319 * </p> 320 * 321 * @param classNameId the primary key of the asset's class 322 * @param classPK the primary key of the asset 323 */ 324 public void enableActivityCounters(long classNameId, long classPK) 325 throws PortalException; 326 327 /** 328 * Returns the activity counter with the given name, owner, and end period 329 * that belong to the given entity. 330 * 331 * @param groupId the primary key of the group 332 * @param classNameId the primary key of the entity's class 333 * @param classPK the primary key of the entity 334 * @param name the counter name 335 * @param ownerType the owner type 336 * @param endPeriod the end period, <code>-1</code> for the latest one 337 * @return the matching activity counter 338 */ 339 @Transactional(propagation = Propagation.SUPPORTS, readOnly = true) 340 public SocialActivityCounter fetchActivityCounterByEndPeriod(long groupId, 341 long classNameId, long classPK, java.lang.String name, int ownerType, 342 int endPeriod); 343 344 /** 345 * Returns the activity counter with the given name, owner, and start period 346 * that belong to the given entity. 347 * 348 * @param groupId the primary key of the group 349 * @param classNameId the primary key of the entity's class 350 * @param classPK the primary key of the entity 351 * @param name the counter name 352 * @param ownerType the owner type 353 * @param startPeriod the start period 354 * @return the matching activity counter 355 */ 356 @Transactional(propagation = Propagation.SUPPORTS, readOnly = true) 357 public SocialActivityCounter fetchActivityCounterByStartPeriod( 358 long groupId, long classNameId, long classPK, java.lang.String name, 359 int ownerType, int startPeriod); 360 361 /** 362 * Returns the latest activity counter with the given name and owner that 363 * belong to the given entity. 364 * 365 * @param groupId the primary key of the group 366 * @param classNameId the primary key of the entity's class 367 * @param classPK the primary key of the entity 368 * @param name the counter name 369 * @param ownerType the owner type 370 * @return the matching activity counter 371 */ 372 @Transactional(propagation = Propagation.SUPPORTS, readOnly = true) 373 public SocialActivityCounter fetchLatestActivityCounter(long groupId, 374 long classNameId, long classPK, java.lang.String name, int ownerType); 375 376 @Transactional(propagation = Propagation.SUPPORTS, readOnly = true) 377 public SocialActivityCounter fetchSocialActivityCounter( 378 long activityCounterId); 379 380 @Transactional(propagation = Propagation.SUPPORTS, readOnly = true) 381 public ActionableDynamicQuery getActionableDynamicQuery(); 382 383 @Transactional(propagation = Propagation.SUPPORTS, readOnly = true) 384 public IndexableActionableDynamicQuery getIndexableActionableDynamicQuery(); 385 386 /** 387 * Returns the OSGi service identifier. 388 * 389 * @return the OSGi service identifier 390 */ 391 public java.lang.String getOSGiServiceIdentifier(); 392 393 /** 394 * Returns all the activity counters with the given name and period offsets. 395 * 396 * <p> 397 * The start and end offsets can belong to different periods. This method 398 * groups the counters by name and returns the sum of their current values. 399 * </p> 400 * 401 * @param groupId the primary key of the group 402 * @param name the counter name 403 * @param startOffset the offset for the start period 404 * @param endOffset the offset for the end period 405 * @return the matching activity counters 406 */ 407 @Transactional(propagation = Propagation.SUPPORTS, readOnly = true) 408 public List<SocialActivityCounter> getOffsetActivityCounters(long groupId, 409 java.lang.String name, int startOffset, int endOffset); 410 411 /** 412 * Returns the distribution of the activity counters with the given name and 413 * period offsets. 414 * 415 * <p> 416 * The start and end offsets can belong to different periods. This method 417 * groups the counters by their owner entity (usually some asset) and 418 * returns a counter for each entity class with the sum of the counters' 419 * current values. 420 * </p> 421 * 422 * @param groupId the primary key of the group 423 * @param name the counter name 424 * @param startOffset the offset for the start period 425 * @param endOffset the offset for the end period 426 * @return the distribution of matching activity counters 427 */ 428 @Transactional(propagation = Propagation.SUPPORTS, readOnly = true) 429 public List<SocialActivityCounter> getOffsetDistributionActivityCounters( 430 long groupId, java.lang.String name, int startOffset, int endOffset); 431 432 /** 433 * Returns all the activity counters with the given name and time period. 434 * 435 * <p> 436 * The start and end period values can belong to different periods. This 437 * method groups the counters by name and returns the sum of their current 438 * values. 439 * </p> 440 * 441 * @param groupId the primary key of the group 442 * @param name the counter name 443 * @param startPeriod the start period 444 * @param endPeriod the end period 445 * @return the matching activity counters 446 */ 447 @Transactional(propagation = Propagation.SUPPORTS, readOnly = true) 448 public List<SocialActivityCounter> getPeriodActivityCounters(long groupId, 449 java.lang.String name, int startPeriod, int endPeriod); 450 451 /** 452 * Returns the distribution of activity counters with the given name and 453 * time period. 454 * 455 * <p> 456 * The start and end period values can belong to different periods. This 457 * method groups the counters by their owner entity (usually some asset) and 458 * returns a counter for each entity class with the sum of the counters' 459 * current values. 460 * </p> 461 * 462 * @param groupId the primary key of the group 463 * @param name the counter name 464 * @param startPeriod the start period 465 * @param endPeriod the end period 466 * @return the distribution of matching activity counters 467 */ 468 @Transactional(propagation = Propagation.SUPPORTS, readOnly = true) 469 public List<SocialActivityCounter> getPeriodDistributionActivityCounters( 470 long groupId, java.lang.String name, int startPeriod, int endPeriod); 471 472 @Override 473 @Transactional(propagation = Propagation.SUPPORTS, readOnly = true) 474 public PersistedModel getPersistedModel(Serializable primaryKeyObj) 475 throws PortalException; 476 477 /** 478 * Returns the social activity counter with the primary key. 479 * 480 * @param activityCounterId the primary key of the social activity counter 481 * @return the social activity counter 482 * @throws PortalException if a social activity counter with the primary key could not be found 483 */ 484 @Transactional(propagation = Propagation.SUPPORTS, readOnly = true) 485 public SocialActivityCounter getSocialActivityCounter( 486 long activityCounterId) throws PortalException; 487 488 /** 489 * Returns a range of all the social activity counters. 490 * 491 * <p> 492 * Useful when paginating results. Returns a maximum of <code>end - start</code> instances. <code>start</code> and <code>end</code> are not primary keys, they are indexes in the result set. Thus, <code>0</code> refers to the first result in the set. Setting both <code>start</code> and <code>end</code> to {@link com.liferay.portal.kernel.dao.orm.QueryUtil#ALL_POS} will return the full result set. If <code>orderByComparator</code> is specified, then the query will include the given ORDER BY logic. If <code>orderByComparator</code> is absent and pagination is required (<code>start</code> and <code>end</code> are not {@link com.liferay.portal.kernel.dao.orm.QueryUtil#ALL_POS}), then the query will include the default ORDER BY logic from {@link com.liferay.portlet.social.model.impl.SocialActivityCounterModelImpl}. If both <code>orderByComparator</code> and pagination are absent, for performance reasons, the query will not have an ORDER BY clause and the returned result set will be sorted on by the primary key in an ascending order. 493 * </p> 494 * 495 * @param start the lower bound of the range of social activity counters 496 * @param end the upper bound of the range of social activity counters (not inclusive) 497 * @return the range of social activity counters 498 */ 499 @Transactional(propagation = Propagation.SUPPORTS, readOnly = true) 500 public List<SocialActivityCounter> getSocialActivityCounters(int start, 501 int end); 502 503 /** 504 * Returns the number of social activity counters. 505 * 506 * @return the number of social activity counters 507 */ 508 @Transactional(propagation = Propagation.SUPPORTS, readOnly = true) 509 public int getSocialActivityCountersCount(); 510 511 /** 512 * Returns the range of tuples that contain users and a list of activity 513 * counters. 514 * 515 * <p> 516 * The counters returned for each user are passed to this method in the 517 * selectedNames array. The method also accepts an array of counter names 518 * that are used to rank the users. 519 * </p> 520 * 521 * <p> 522 * Useful when paginating results. Returns a maximum of <code>end - 523 * start</code> instances. <code>start</code> and <code>end</code> are not 524 * primary keys, they are indexes in the result set. Thus, <code>0</code> 525 * refers to the first result in the set. Setting both <code>start</code> 526 * and <code>end</code> to {@link QueryUtil#ALL_POS} will return the full 527 * result set. 528 * </p> 529 * 530 * @param groupId the primary key of the group 531 * @param rankingNames the ranking counter names 532 * @param selectedNames the counter names that will be returned with each 533 user 534 * @param start the lower bound of the range of results 535 * @param end the upper bound of the range of results (not inclusive) 536 * @return the range of matching tuples 537 */ 538 @Transactional(propagation = Propagation.SUPPORTS, readOnly = true) 539 public List<Tuple> getUserActivityCounters(long groupId, 540 java.lang.String[] rankingNames, java.lang.String[] selectedNames, 541 int start, int end); 542 543 /** 544 * Returns the number of users having a rank based on the given counters. 545 * 546 * @param groupId the primary key of the group 547 * @param rankingNames the ranking counter names 548 * @return the number of matching users 549 */ 550 @Transactional(propagation = Propagation.SUPPORTS, readOnly = true) 551 public int getUserActivityCountersCount(long groupId, 552 java.lang.String[] rankingNames); 553 554 /** 555 * Increments the <code>user.achievements</code> counter for a user. 556 * 557 * <p> 558 * This method should be used by an external achievement class when the 559 * users unlocks an achievement. 560 * </p> 561 * 562 * @param userId the primary key of the user 563 * @param groupId the primary key of the group 564 */ 565 public void incrementUserAchievementCounter(long userId, long groupId) 566 throws PortalException; 567 568 /** 569 * Updates the social activity counter in the database or adds it if it does not yet exist. Also notifies the appropriate model listeners. 570 * 571 * @param socialActivityCounter the social activity counter 572 * @return the social activity counter that was updated 573 */ 574 @Indexable(type = IndexableType.REINDEX) 575 public SocialActivityCounter updateSocialActivityCounter( 576 SocialActivityCounter socialActivityCounter); 577 }