com.ning.billing.entitlement.api.EntitlementApi Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of killbill-api Show documentation
The newest version!
/*
 * Copyright 2010-2013 Ning, Inc.
 *
 * Ning licenses this file to you under the Apache License, version 2.0
 * (the "License"); you may not use this file except in compliance with the
 * License.  You may obtain a copy of the License at:
 *
 *    http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the
 * License for the specific language governing permissions and limitations
 * under the License.
 */

package com.ning.billing.entitlement.api;

import com.ning.billing.catalog.api.BillingActionPolicy;
import com.ning.billing.catalog.api.PlanPhaseSpecifier;
import com.ning.billing.util.callcontext.CallContext;
import com.ning.billing.util.callcontext.TenantContext;
import org.joda.time.LocalDate;

import java.util.List;
import java.util.UUID;

/**
 * Primary API to manage the creation and retrieval of Entitlement.
 *
 */
public interface EntitlementApi {

    /**
     *
     * Create a new entitlement for that account.
     * 
     * The PlanPhaseSpecifier should refer to a ProductCategory.BASE of
     * ProductCategory.STANDALONE.
     *
     * @param accountId     the account id
     * @param spec          the product specification for that new entitlement
     * @param externalKey   the external key for that entitlement-- which must be unique in the system
     * @param effectiveDate the date at which the entitlement should start
     * @param context       the context
     * @return              a new entitlement
     *
     * @throws EntitlementApiException if the system fail to create the Entitlement.
     */
    public Entitlement createBaseEntitlement(UUID accountId, PlanPhaseSpecifier spec, String externalKey, LocalDate effectiveDate, CallContext context)
            throws EntitlementApiException;

    /**
     *
     * Adds an ADD_ON entitlement to previously created entitlement.
     * 

     * The PlanPhaseSpecifier should refer to a ProductCategory.ADD_ON.
     * The new entitlement will be bundled using the externalKey that was specified when creating the
     * base entitlement.
     *
     * @param bundleId          the id of the bundle
     * @param spec              the product specification for that new entitlement
     * @param effectiveDate the date at which the entitlement should start
     * @param context           the context
     * @return                  a new entitlement
     *
     * @throws EntitlementApiException if the system fail to create the Entitlement
     */
    public Entitlement addEntitlement(UUID bundleId, PlanPhaseSpecifier spec, LocalDate effectiveDate, CallContext context)
            throws EntitlementApiException;


    /**
     * Simulate a change of product for the BP on that bundle and return the effect it would have on the existing ADD_ON-- if any.
     *
     * @param bundleId          the id of the bundle
     * @param targetProductName the target product name for the BP
     * @param effectiveDate     the date at which the change would occur
     * @param context           the context
     * @return                  the status for the existing ADD_ON Entitlement
     *
     * @throws EntitlementApiException if this operation is not carried on a base plan.
     */
    public List getDryRunStatusForChange(UUID bundleId, final String targetProductName, final LocalDate effectiveDate, final TenantContext context)
            throws EntitlementApiException;


    /**
     * Will pause all entitlements associated with the base entitlement. If there are no ADD_ONN this is only the base entitlement.
     *
     * @param bundleId
     * @param effectiveDate
     * @param context
     *
     *  @throws EntitlementApiException if the system fail to find the base Entitlement
     */
    public void pause(UUID bundleId, LocalDate effectiveDate, CallContext context)
            throws EntitlementApiException;


    /**
     * Will resume all entitlements associated with the base entitlement. If there are no ADD_ONN this is only the base entitlement.
     *
     * @param bundleId
     * @param effectiveDate
     * @param context
     *
     *  @throws EntitlementApiException if the system fail to find the base Entitlement
     */
    public void resume(UUID bundleId, LocalDate effectiveDate, CallContext context)
            throws EntitlementApiException;

    /**
     * Will add a blocking event for the specified service associated with the base entitlement.
     *
     * @param bundleId          the id of the bundle
     * @param serviceName       the name of the service
     * @param effectiveDate     the date at which the operation should occur
     * @param blockBilling      whether this event should block billing
     * @param blockEntitlement  whether this event should block entitlement
     * @param blockChange       whether this event should block any change
     * @param context           the context
     *
     * @throws EntitlementApiException if the system fail to find the base Entitlement
    public void block(UUID bundleId, String serviceName, LocalDate effectiveDate, boolean blockBilling, boolean blockEntitlement, boolean blockChange, CallContext context)
            throws EntitlementApiException;
    */

    /**
     * Will unblock all entitlements associated with the base entitlement. If there are no ADD_ONN this is only the base entitlement.
     *
     * @param bundleId          the id of the bundle
     * @param serviceName       the name of the service
     * @param effectiveDate     the date at which the operation should occur
     * @param context           the context
     *
     * @throws EntitlementApiException if the system fail to find the base Entitlement
    public void unblock(UUID bundleId, String serviceName, LocalDate effectiveDate, CallContext context)
            throws EntitlementApiException;
     */

    /**
     *
     * Retrieves an Entitlement using its id.
     *
     * @param id        the id of the entitlement
     * @param context   the context
     * @return          the entitlement
     *
     * @throws EntitlementApiException if the entitlement does not exist
     */
    public Entitlement getEntitlementForId(UUID id, TenantContext context) throws EntitlementApiException;

    /**
     *
     * Retrieves all the Entitlement attached to the base entitlement.
     *
     * @param bundleId              the id of the bundle
     * @param context               the context
     * @return                      a list of entitlements
     *
     * @throws EntitlementApiException if the entitlement does not exist
     */
    public List getAllEntitlementsForBundle(UUID bundleId, TenantContext context)
            throws EntitlementApiException;

    /**
     *
     * Retrieves all the Entitlement for a given account and matching an external key.
     *
     * @param accountId     the account id
     * @param externalKey   the external key
     * @param context       the context
     *
     * @return              a list of entitlements
     *
     * @throws EntitlementApiException if the account does not exist
     */
    public List getAllEntitlementsForAccountIdAndExternalKey(UUID accountId, String externalKey, TenantContext context)
            throws EntitlementApiException;

    /**
     *
     * Retrieves all the Entitlement for a given account.
     *
     * @param accountId     the account id
     * @param context       the context
     *
     * @return              a list of entitlements
     *
     * @throws EntitlementApiException if the account does not exist
     */
    public List getAllEntitlementsForAccountId(UUID accountId, TenantContext context) throws EntitlementApiException;

    /**
     * Transfer all the Entitlement For the source account and matching the external key to the destination account.
     * 

     * The date is interpreted by the system to be in the timezone specified at the destination Account.
     * 

     * The Entitlement on the source account will be cancelled at effective date and the Entitlement
     * on the destination account will be created at the effectiveDate.
     *
     * @param sourceAccountId   the unique id for the account on which the bundle will be transferred For
     * @param destAccountId     the unique id for the account on which the bundle will be transferred to
     * @param externalKey       the externalKey for the bundle
     * @param effectiveDate     the date at which this transfer should occur
     * @param context           the user context
     *
     * @return                  the id of the newly created bundle for the destination account
     *
     * @throws EntitlementApiException if the system could not transfer the entitlements
     *
     */
    public UUID transferEntitlements(final UUID sourceAccountId, final UUID destAccountId, final String externalKey, final LocalDate effectiveDate,
                                     final CallContext context)
            throws EntitlementApiException;

    /**
     * Transfer all the Entitlement for the source account and matching the external key to the destination account.
     * 

     * The date is interpreted by the system to be in the timezone specified at the destination Account.
     * 

     * The Entitlement on the source account will be cancelled at effective date and the Entitlement
     * on the destination account will be created at the effectiveDate. The billingPolicy will be used to override
     * the default billing behavior for the cancellation of the subscriptions on the source account.
     *
     *
     * @param sourceAccountId   the unique id for the account on which the bundle will be transferred For
     * @param destAccountId     the unique id for the account on which the bundle will be transferred to
     * @param externalKey       the externalKey for the bundle
     * @param effectiveDate     the date at which this transfer should occur
     * @param billingPolicy     the override billing policy
     * @param context           the user context
     *
     * @return                  the id of the newly created base entitlement for the destination account
     *
     * @throws EntitlementApiException if the system could not transfer the entitlements
     *
     */
    public UUID transferEntitlementsOverrideBillingPolicy(final UUID sourceAccountId, final UUID destAccountId, final String externalKey, final LocalDate effectiveDate,
                                                          final BillingActionPolicy billingPolicy, final CallContext context)
            throws EntitlementApiException;

}