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    }