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    }