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