org.starhope.appius.mb
Class UserEnrolment

java.lang.Object
  org.starhope.appius.util.SimpleDataRecord<UserEnrolment>
      org.starhope.appius.mb.UserEnrolment

All Implemented Interfaces:

com.whirlycott.cache.Cacheable, Serializable, Comparable<UserEnrolment>, Invoiceable, CastsToJSON, CTime, DataRecord, HasSubversionRevision

public class UserEnrolment
extends SimpleDataRecord<UserEnrolment>
implements Invoiceable, CastsToJSON

This class represents an instance of a purchased enrolment (subscription) to a game, as bound to a particular user and period of time.

Author:

brpocock@star-hope.org, Tim Heys

See Also:

Serialized Form

Field Summary

private BigDecimal	authSubID Authorize.net subscription ID
private Date	begins start date
private Date	expires expiry date
private int	id database ID
private boolean	isActivated Has this enrolment been activated already?
private String	orderCode order code
private static char[]	orderCodeChars An often-used array of characters used to create order codes.
private String	orderSource order source
private int	productID Enrolment product ID
private static long	serialVersionUID Java serialisation unique ID
private int	userID The user who owns this enrolment

Fields inherited from class org.starhope.appius.util.SimpleDataRecord

myLoader, timeLastChanged, timeLastSaved

Constructor Summary

UserEnrolment(String order_source, int product_id, int user_id)
Create a new enrolment for the given user.

UserEnrolment(String orderSource2, String orderCode2)
WRITEME: Document this constructor brpocock@star-hope.org

UserEnrolment(UserEnrolmentSQLLoader userEnrolmentSQLLoader)
WRITEME: Document this constructor brpocock@star-hope.org

Method Summary

void	activate(boolean newEnrolment) XXX: This method should probably be checking activatedUser.isPaidMember () instead of requiring a boolean into it
private void	add(int months, int days) Extend the expiration date by a given amount.
void	cancelNow() cancel the enrolment, effective immediately.
void	checkStale() Indicates that a data record is stale and needs to be refreshed
private void	continueEnrolment() Based upon the current expiry date, extend the expiry by the number of months and days indicated by the enrolment type.
private void	generateOrderCode() Create a pseudo-random, unique order code consisting of the approved letters and numbers in orderCodeChars
private String	genRandomOrderCode() Create a 10-character sequence using the “non-ambiguous” character set of order code characters.
static Collection<UserEnrolment>	getAllForUserID(int userID)
BigDecimal	getAmount()
BigDecimal	getAuthSubID()
Date	getBegins()
AbstractPerson	getBuyer() TODO: refactor payment gateways to use the buyer information: promote this up to Invoiceable interface.
static UserEnrolment	getBySourceAndCode(String orderSource, String orderCode) Retrieve a User Enrolment based off the invoice number split into orderSource and orderCode.
int	getCacheableID() Note that all records must have either a numeric ID ( DataRecord.getCacheableID() or a string identifier ( DataRecord.getCacheableIdent() or both.
String	getCacheableIdent() Note that all records must have either a numeric ID ( DataRecord.getCacheableID() or a string identifier ( DataRecord.getCacheableIdent() or both.
Currency	getCurrency()
String	getDescription() Get the description of the subscription: typically, this says a subscription to a given product (“Subscription to Tootsville”), plus “for,” and the display name of the subscriber.
Enrolment	getEnrolment()
Date	getExpires()
int	getID()
String	getInvoiceID()
char	getInvoiceIDPrefix()
private Date	getLastExpiration() Checks all enrolments for current user to determine when their last expiration ends and if it ends before today.
Payment	getLastPayment()
static UserEnrolment[]	getLastTwoYearsForUserID(int userID) Get all enrolments for a given user in the past two years from today's date.
String	getOrderCode()
static String	getOrderCode(String orderNumber) get the order code from an order number
static char[]	getOrderCodeChars() Get a set of characters that are unlikely to be confused for one another.
String	getOrderSource()
static String	getOrderSource(String orderNumber) get the order source from an order number
int	getProductID()
Date	getRecurs()
String	getSubversionRevision() Return the Subversion revision level of this class's source code file, as supplied via the special "$Rev: " sequence.
String	getTitle()
AbstractUser	getUser()
int	getUserID()
void	insert() insert the enrolment into the database
boolean	isActive()
boolean	isRecurring() find whether this is a recurring enrolment type
void	killEnrolment() set both the start and end effective dates to the epoch
void	setAuthSubID(BigDecimal authSubID1)
void	setAuthSubID(String authSubID2) set the authorize.net subscription ID
void	setBegins(Date newBegins)
void	setEnrolment(Enrolment newEnrolment)
void	setExpires(Date newExpires)
void	setID(int newID)
void	setOrderCode(String orderCode1)
void	setOrderSource(String orderSource1)
void	setProductID(int productID1)
void	setUser(GeneralUser newUser)
void	setUserID(int userID1)
private void	startEnrolment() WRITEME: document this method (twheys@gmail.com, Sep 24, 2009)
org.json.JSONObject	toJSON() This returns a copy of the object's data cast into a JSON form.
String	toString()

Methods inherited from class org.starhope.appius.util.SimpleDataRecord

changed, compareTo, equals, finalize, getRecordLoader, getTimeLastChanged, getTimeLastSaved, hashCode, isBeingLoaded, markAsLoaded, markAsSaved, markForReload, onRemove, onRetrieve, onStore, save, setRecordLoader

Methods inherited from class java.lang.Object

clone, getClass, notify, notifyAll, wait, wait, wait

Field Detail

orderCodeChars

private static final char[] orderCodeChars

An often-used array of characters used to create order codes.

This excludes letters and digits which reasonably might be confused in some handwriting or stylised fonts: O/Q/0, I/1, 2/Z, 5/S, 7/T, and U/V.

Note that this gives us a base-21 system, thus possible permutations are:

 n×1                   21
 n×2                  441
 n×3                9,261
 n×4              194,481
 n×5            4,084,101
 n×6           85,766,121
 n×7        1,801,088,541
 n×8       37,822,859,361
 n×9      764,280,046,581
 n×10  16,679,880,978,201
 

∴ we have about 17 trillion available 10-digit order codes even after excluding all of those potential characters

serialVersionUID

private static final long serialVersionUID

Java serialisation unique ID

See Also:

Constant Field Values

authSubID

private BigDecimal authSubID

Authorize.net subscription ID

begins

private Date begins

start date

expires

private Date expires

expiry date

id

private int id

database ID

isActivated

private volatile boolean isActivated

Has this enrolment been activated already?

orderCode

private String orderCode

order code

orderSource

private String orderSource

order source

productID

private int productID

Enrolment product ID

userID

private int userID

The user who owns this enrolment

Constructor Detail

UserEnrolment

public UserEnrolment(String order_source,
                     int product_id,
                     int user_id)
              throws NotFoundException

Create a new enrolment for the given user.

Parameters:

order_source - order source code

product_id - the product for which the user is enrolling

user_id - the user being enrolled

Throws:

NotFoundException - if the enrolment type is not found.

UserEnrolment

public UserEnrolment(String orderSource2,
                     String orderCode2)

WRITEME: Document this constructor brpocock@star-hope.org

Parameters:

orderSource2 - WRITEME

orderCode2 - WRITEME

UserEnrolment

public UserEnrolment(UserEnrolmentSQLLoader userEnrolmentSQLLoader)

WRITEME: Document this constructor brpocock@star-hope.org

Parameters:

userEnrolmentSQLLoader - WRITEME

Method Detail

getAllForUserID

public static Collection<UserEnrolment> getAllForUserID(int userID)

Parameters:

userID - user enrolled

Returns:

array of all current enrolments

getBySourceAndCode

public static UserEnrolment getBySourceAndCode(String orderSource,
                                               String orderCode)
                                        throws NotFoundException

Retrieve a User Enrolment based off the invoice number split into orderSource and orderCode.

Parameters:

orderSource - The source of the order (ex. 'auth')

orderCode - The code of the order

Returns:

A UserEnrolment with the invoice number of {orderSource}-{orderCode}

Throws:

NotFoundException - if an enrolment cannot be found with the given orderSource and orderCode.

getLastTwoYearsForUserID

public static UserEnrolment[] getLastTwoYearsForUserID(int userID)

Get all enrolments for a given user in the past two years from today's date.

Parameters:

userID - user enrolled

Returns:

array of all current enrolments

getOrderCode

public static String getOrderCode(String orderNumber)

get the order code from an order number

Parameters:

orderNumber - an order number string

Returns:

the order code part (after the “-”)

getOrderCodeChars

public static char[] getOrderCodeChars()

Get a set of characters that are unlikely to be confused for one another.

Returns:

the characters permitted in order codes.

See Also:

orderCodeChars

getOrderSource

public static String getOrderSource(String orderNumber)

get the order source from an order number

Parameters:

orderNumber - an order number

Returns:

the order source (part before the “-”)

activate

public void activate(boolean newEnrolment)

XXX: This method should probably be checking activatedUser.isPaidMember () instead of requiring a boolean into it

Parameters:

newEnrolment - true if this is a new account

add

private void add(int months,
                 int days)

Extend the expiration date by a given amount. Months are added based upon the calendar day; i.e. we take into account the length differences of months and so forth; then, additional days are appended.

Out of paranoia, the base date (to which the new months & days are added) will be set to the later of either the current expiry date, or the current date. This means that if an enrolment expires in the past, and is then extended, it will end at the proper date from now; but if it has not yet expired, the renewal will be tacked onto the end.

Parameters:

months - months to extend

days - days to extend.

cancelNow

public void cancelNow()

cancel the enrolment, effective immediately.

checkStale

public void checkStale()

Description copied from interface: DataRecord

Indicates that a data record is stale and needs to be refreshed

Specified by:

checkStale in interface DataRecord

Overrides:

checkStale in class SimpleDataRecord<UserEnrolment>

See Also:

SimpleDataRecord.checkStale()

continueEnrolment

private void continueEnrolment()

Based upon the current expiry date, extend the expiry by the number of months and days indicated by the enrolment type.

generateOrderCode

private void generateOrderCode()

Create a pseudo-random, unique order code consisting of the approved letters and numbers in orderCodeChars

genRandomOrderCode

private String genRandomOrderCode()

Create a 10-character sequence using the “non-ambiguous” character set of order code characters. This routine does not attempt to validate whether that code is in use. Used internally by the method generateOrderCode(), for which you probably are looking, if you found this.

Returns:

the order code

getAmount

public BigDecimal getAmount()

Specified by:

getAmount in interface Invoiceable

Returns:

the price of a purchase

See Also:

Invoiceable.getAmount()

getAuthSubID

public BigDecimal getAuthSubID()

Returns:

authorize.net subscriber ID

getBegins

public Date getBegins()

Returns:

begin date

getBuyer

public AbstractPerson getBuyer()

Description copied from interface: Invoiceable

TODO: refactor payment gateways to use the buyer information: promote this up to Invoiceable interface.

Specified by:

getBuyer in interface Invoiceable

Returns:

the buyer, paying-for this order

See Also:

Invoiceable.getBuyer()

getCacheableID

public int getCacheableID()
                   throws NotFoundException

Description copied from interface: DataRecord

Note that all records must have either a numeric ID ( DataRecord.getCacheableID() or a string identifier ( DataRecord.getCacheableIdent() or both.

Specified by:

getCacheableID in interface DataRecord

Returns:

an unique ID number

Throws:

NotFoundException - if the item doesn't have a distinct numeric ID

See Also:

DataRecord.getCacheableID()

getCacheableIdent

public String getCacheableIdent()
                         throws NotFoundException

Description copied from interface: DataRecord

Note that all records must have either a numeric ID ( DataRecord.getCacheableID() or a string identifier ( DataRecord.getCacheableIdent() or both.

Specified by:

getCacheableIdent in interface DataRecord

Returns:

an unique identifier string

Throws:

NotFoundException - if the item doesn't have a distinct string identifier

See Also:

DataRecord.getCacheableIdent()

getCurrency

public Currency getCurrency()

Specified by:

getCurrency in interface Invoiceable

Returns:

the currency used to describe the price in Invoiceable.getAmount()

See Also:

Invoiceable.getCurrency()

getDescription

public String getDescription()

Get the description of the subscription: typically, this says a subscription to a given product (“Subscription to Tootsville”), plus “for,” and the display name of the subscriber. This is an user-visible string.

Returns:

the user-visible description of this user enrolment

getEnrolment

public Enrolment getEnrolment()

Returns:

enrolment

getExpires

public Date getExpires()

Returns:

expiry

getID

public int getID()

Returns:

unique ID

getInvoiceID

public String getInvoiceID()

Specified by:

getInvoiceID in interface Invoiceable

Returns:

the invoice ID ("order number") for payment

See Also:

Invoiceable.getInvoiceID()

getInvoiceIDPrefix

public char getInvoiceIDPrefix()

Specified by:

getInvoiceIDPrefix in interface Invoiceable

Returns:

A single-character code representing this class of invoiceable items. This permits easy identification of the type of object being paid for, regardless of how we come across the invoice number.

See Also:

Invoiceable.getInvoiceIDPrefix()

getLastExpiration

private Date getLastExpiration()

Checks all enrolments for current user to determine when their last expiration ends and if it ends before today. Returns the date farthest into the future.

Returns:

the last (future-most) expiration date

getLastPayment

public Payment getLastPayment()
                       throws NotFoundException

Returns:

last payment

Throws:

NotFoundException - if nobody's paid anything yet

getOrderCode

public String getOrderCode()

Returns:

order code

getOrderSource

public String getOrderSource()

Returns:

order source

getProductID

public int getProductID()

Returns:

product ID of enrolment

getRecurs

public Date getRecurs()

Returns:

the next date where billing will reoccur

getSubversionRevision

public String getSubversionRevision()

Description copied from interface: HasSubversionRevision

Return the Subversion revision level of this class's source code file, as supplied via the special "$Rev: " sequence.

As an example,the Subversion revision string for this file is "$Rev: 1968 $"

 
 @Override
 public String getSubversionRevision () {
        return "$Rev: ";
 }
 

Specified by:

getSubversionRevision in interface HasSubversionRevision

Returns:

The Subversion revision level for this class's source code file.

See Also:

HasSubversionRevision.getSubversionRevision()

getTitle

public String getTitle()

Specified by:

getTitle in interface Invoiceable

Returns:

the description of a purchase

See Also:

Invoiceable.getTitle()

getUser

public AbstractUser getUser()

Returns:

user who is enrolled

getUserID

public int getUserID()

Returns:

the user ID of the user who �owns� this enrolment

insert

public void insert()
            throws SQLException

insert the enrolment into the database

Throws:

SQLException - if the record can't be inserted into the database

isActive

public boolean isActive()

Returns:

true if the enrolment hasn't expired yet

isRecurring

public boolean isRecurring()

find whether this is a recurring enrolment type

Returns:

true, if this is a recurring enrolment type

killEnrolment

public void killEnrolment()

set both the start and end effective dates to the epoch

setAuthSubID

@Setter(getter="getAuthSubID")
@OpEd(advice="The Authorize.Net (or other payment authenticator) Subscription ID number",
      isAdvanced=true,
      label="Authenticator Subscription ID")
public void setAuthSubID(BigDecimal authSubID1)

Parameters:

authSubID1 - authorize.net subscription ID

setAuthSubID

public void setAuthSubID(String authSubID2)
                  throws NumberFormatException

set the authorize.net subscription ID

Parameters:

authSubID2 - authorize.net subscription ID

Throws:

NumberFormatException - if the id or something can't be interpreted? but I don't know what circumstances might cause this, probably a non-numeric subscriber ID being returned from the provider? WRITEME

setBegins

@Setter(getter="getBegins")
public void setBegins(Date newBegins)

Parameters:

newBegins - begin date

setEnrolment

public void setEnrolment(Enrolment newEnrolment)

Parameters:

newEnrolment - enrolment product

setExpires

public void setExpires(Date newExpires)

Parameters:

newExpires - expiry date

setID

public void setID(int newID)

Parameters:

newID - the id to set

setOrderCode

public void setOrderCode(String orderCode1)

Parameters:

orderCode1 - order code

setOrderSource

public void setOrderSource(String orderSource1)

Parameters:

orderSource1 - order source

setProductID

public void setProductID(int productID1)

Parameters:

productID1 - enrolment product

setUser

public void setUser(GeneralUser newUser)

Parameters:

newUser - user enrolled

setUserID

public void setUserID(int userID1)

Parameters:

userID1 - user enrolled

startEnrolment

private void startEnrolment()

WRITEME: document this method (twheys@gmail.com, Sep 24, 2009)

Set the proper enrolment start date. This might not work right?

toJSON

public org.json.JSONObject toJSON()

Description copied from interface: CastsToJSON

This returns a copy of the object's data cast into a JSON form.

Specified by:

toJSON in interface CastsToJSON

Returns:

The string representing this object in JSON format

toString

public String toString()

Overrides:

toString in class SimpleDataRecord<UserEnrolment>

See Also:

Object.toString()