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