com.pluraprocessing.node.affiliate.desktop
Interface IPluraConnector

All Known Implementing Classes:

JavaPluraConnector

public interface IPluraConnector

Interface IPluraConnector.

Each class that implements IPluraConnector manages threads that run Plura. To ensure that Plura threads are not abandoned, ALWAYS invoke stop() after you invoke start(), even if your application exits on error.

There are 2 types of applications that Plura can run on a client computer: (1) computationally intensive applications and (2) bandwidth intensive applications. For computational applications, the percentageCPU passed into an IPluraConnector implementation is used to monitor the CPU usage on the client computer; bandwidth will not be used for the computations in these applications. For bandwidth applications, the bandwidthPercent passed into an IPluraConnector implementation is used to monitor the bandwidth usage on the client computer; CPU usage will be negligable for the computations in these applications. At any given moment, Plura may choose to run either computational applications or bandwidth applications. It may therefore be the case that Plura appears to be using very little of the client computer's CPU. This does not mean that Plura isn't running--please contact Plura at support@pluraprocessing.com if you are concerned that your clients aren't completing Plura work units. We can work with you to determine if this is the case.

We recommend that you allocate 256 MB of RAM to run Plura in your Java application. If there is not enough RAM on the client machine to do this, a good rule of thumb is: 64 MB plus 16 MB per Plura thread. For example, on a machine with 4 cores (running 4 Plura threads): 64 MB + 4 * (16 MB) = 128 MB. You can add this amount to your existing -Xmx Java option.

This code will run in Java 1.6 and above.

Method Summary

void	changeBandwidthUsage(double percentBandwidth) Change bandwidth usage on the client computer.
void	changeCpuUsage(double percentageCPU) Change CPU usage on the client computer.
void	changeMaxPluraThreads(int maxPluraThreads) Change the maximum number of Plura threads to run on the client computer.
int	getWorkUnitsCompletedByClient(java.lang.String clientId, java.util.Calendar dateToRetrieve) Get the number of work units completed by the specified client on the specifed day.
void	init(java.lang.String affiliateId, double percentageCPU, double bandwidthPercent, java.lang.String clientId, int maxPluraThreads) Initializes the Plura Connection with the specified parameters.
void	start() Start running Plura on the client's computer.
void	stop() Stop running Plura on the client's computer.

Method Detail

init

void init(java.lang.String affiliateId,
          double percentageCPU,
          double bandwidthPercent,
          java.lang.String clientId,
          int maxPluraThreads)
          throws PluraParameterException,
                 PluraStateException

Initializes the Plura Connection with the specified parameters.

Parameters:

affiliateId - The affiliate id to be credited with the work units completed. This parameter is optional; null may be passed in. If not null, it must be a String that is 36 characters or less.

percentageCPU - The percentage of the client computer's CPU to use for CPU-intensive applications. Must be less than 1 and greater than 0.

bandwidthPercent - The percentage of the client's bandwidth to use for bandwidth-intensive applications. Must be less than 1 and greater than 0.

clientId - The id of the current client. This parameter is optional; if null or "" are passed in, a random id will be generated for the client. Must be less than 40 characters in length.

maxPluraThreads - The maximum number of Plura threads that you wish to run on the client's computer. In general, this number should be used to specify the number of cores that you wish to utilize on the client's computer. This number represents a MAXIMUM--Plura may decide to start fewer threads, depending on the condition of the client's computer. Must be greater than zero.

Throws:

PluraParameterException - If at least one of the inputs passed into this method is invalid.

PluraStateException - If this method is invoked while Plura is running (after start() has been invoked and before stop() has been invoked).

start

void start()
           throws PluraInitializationException

Start running Plura on the client's computer.

Throws:

PluraInitializationException - If this method is invoked before init(String, double, double, String) is invoked.

stop

void stop()

Stop running Plura on the client's computer.

changeCpuUsage

void changeCpuUsage(double percentageCPU)
                    throws PluraInitializationException,
                           PluraParameterException,
                           PluraStateException

Change CPU usage on the client computer. A PluraStateException will be thrown if Plura is running when this method is invoked.

Parameters:

percentageCPU - The percentage of the client computer's CPU to use. Must be less than 1 and greater than 0.

Throws:

PluraInitializationException - If this method is invoked before init(String, double, double, String) is invoked.

PluraParameterException - If at least one of the inputs passed into this method is invalid.

PluraStateException - If this method is invoked while Plura is running (after start() has been invoked and before stop() has been invoked).

changeBandwidthUsage

void changeBandwidthUsage(double percentBandwidth)
                          throws PluraInitializationException,
                                 PluraParameterException,
                                 PluraStateException

Change bandwidth usage on the client computer. A PluraStateException will be thrown if Plura is running when this method is invoked.

Parameters:

percentBandwidth - The percentage of the client computer's bandwidth to use. Must be less than 1 and greater than 0.

Throws:

PluraInitializationException - If this method is invoked before init(String, double, double, String) is invoked.

PluraParameterException - If at least one of the inputs passed into this method is invalid.

PluraStateException - If this method is invoked while Plura is running (after start() has been invoked and before stop() has been invoked).

changeMaxPluraThreads

void changeMaxPluraThreads(int maxPluraThreads)
                           throws PluraInitializationException,
                                  PluraParameterException,
                                  PluraStateException

Change the maximum number of Plura threads to run on the client computer. A PluraStateException will be thrown if Plura is running when this method is invoked.

Parameters:

maxPluraThreads - The maximum number of Plura threads that you wish to run on the client's computer. In general, this number should be used to specify the number of cores that you wish to utilize on the client's computer. This number represents a MAXIMUM--Plura may decide to start fewer threads, depending on the condition of the client's computer. Must be greater than zero.

Throws:

PluraInitializationException - If this method is invoked before init(String, double, double, String) is invoked.

PluraParameterException - If at least one of the inputs passed into this method is invalid.

PluraStateException - If this method is invoked while Plura is running (after start() has been invoked and before stop() has been invoked).

getWorkUnitsCompletedByClient

int getWorkUnitsCompletedByClient(java.lang.String clientId,
                                  java.util.Calendar dateToRetrieve)
                                  throws PluraParameterException,
                                         PluraInitializationException,
                                         PluraIntervalException,
                                         PluraIOException

Get the number of work units completed by the specified client on the specifed day. A client's work units for a given day will be available 48 hours after the day is over.

Parameters:

clientId - The id of the client for which to retrieve the number of work units.

dateToRetrieve - The day for which to retrieve the number of work units. The time part of this parameter is not used.

Returns:

Number of work units.

Throws:

PluraParameterException - If at least one of the inputs passed into this method is invalid.

PluraInitializationException - If this method is invoked before init(String, double, double, String) is invoked.

PluraIntervalException - If this method is invoked more frequently than permitted. (It may only be invoked once every 10 minutes.)

PluraIOException - If there is a problem communicating with Plura's servers.