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    }