Skip to content
Permalink
Browse files

Issue #572: Fretboard: Complete kdoc

Closes #572: Fretboard: Complete kdoc
  • Loading branch information...
fercarcedo authored and pocmo committed Aug 8, 2018
1 parent 40d000b commit c874c343cab18fe64f45ba8eb9a726f829fe06b9
Showing with 106 additions and 13 deletions.
  1. +15 −0 components/service/fretboard/src/main/java/mozilla/components/service/fretboard/DeviceUuidFactory.kt
  2. +5 −0 ...ents/service/fretboard/src/main/java/mozilla/components/service/fretboard/ExperimentDescriptor.kt
  3. +5 −0 ...rvice/fretboard/src/main/java/mozilla/components/service/fretboard/ExperimentDownloadException.kt
  4. +42 −0 ...nents/service/fretboard/src/main/java/mozilla/components/service/fretboard/ExperimentEvaluator.kt
  5. +6 −0 ...nents/service/fretboard/src/main/java/mozilla/components/service/fretboard/ExperimentsSnapshot.kt
  6. +5 −2 components/service/fretboard/src/main/java/mozilla/components/service/fretboard/Fretboard.kt
  7. +1 −0 ...ents/service/fretboard/src/main/java/mozilla/components/service/fretboard/JSONExperimentParser.kt
  8. +3 −0 ...ain/java/mozilla/components/service/fretboard/scheduler/jobscheduler/JobSchedulerSyncScheduler.kt
  9. +3 −0 ...ce/fretboard/src/main/java/mozilla/components/service/fretboard/scheduler/jobscheduler/SyncJob.kt
  10. +1 −0 ...s/service/fretboard/src/main/java/mozilla/components/service/fretboard/source/kinto/HttpClient.kt
  11. +7 −6 .../service/fretboard/src/main/java/mozilla/components/service/fretboard/source/kinto/KintoClient.kt
  12. +4 −3 ...retboard/src/main/java/mozilla/components/service/fretboard/source/kinto/KintoExperimentSource.kt
  13. +4 −2 ...oard/src/main/java/mozilla/components/service/fretboard/storage/flatfile/ExperimentsSerializer.kt
  14. +5 −0 .../src/main/java/mozilla/components/service/fretboard/storage/flatfile/FlatFileExperimentStorage.kt
@@ -7,7 +7,22 @@ package mozilla.components.service.fretboard
import android.content.Context
import java.util.UUID

/**
* Class used to generate a random UUID for the device
* and store it persistent in shared preferences.
*
* If the UUID was already generated it returns the stored one
*
* @param context context
*/
internal class DeviceUuidFactory(context: Context) {
/**
* Unique UUID for the current android device. As with all UUIDs,
* this unique ID is "very highly likely" to be unique across all Android
* devices. Much more so than ANDROID_ID is
*
* The UUID is generated with <code>UUID.randomUUID()</code>
*/
val uuid by lazy {
val preferences = context
.getSharedPreferences(PREFS_FILE, Context.MODE_PRIVATE)
@@ -4,4 +4,9 @@

package mozilla.components.service.fretboard

/**
* Class used to identify an experiment
*
* @property name experiment name
*/
data class ExperimentDescriptor(val name: String)
@@ -4,4 +4,9 @@

package mozilla.components.service.fretboard

/**
* Exception while downloading experiments from the server
*
* @property message exception message
*/
class ExperimentDownloadException(override val message: String?) : Exception(message)
@@ -8,7 +8,23 @@ import android.content.Context
import android.text.TextUtils
import java.util.zip.CRC32

/**
* Class used to determine if a specific experiment should be enabled or not
* for the device the app is running in
*
* @property valuesProvider provider for the device's values
*/
internal class ExperimentEvaluator(private val valuesProvider: ValuesProvider = ValuesProvider()) {
/**
* Determines if a specific experiment should be enabled or not for the device
*
* @param context context
* @param experimentDescriptor experiment descriptor
* @param experiments list of all experiments
* @param userBucket device bucket
*
* @return experiment object if the device is part of the experiment, null otherwise
*/
fun evaluate(
context: Context,
experimentDescriptor: ExperimentDescriptor,
@@ -22,6 +38,14 @@ internal class ExperimentEvaluator(private val valuesProvider: ValuesProvider =
}
}

/**
* Finds an experiment given its descriptor
*
* @param descriptor experiment descriptor
* @param experiments experiment list
*
* @return found experiment or null
*/
fun getExperiment(descriptor: ExperimentDescriptor, experiments: List<Experiment>): Experiment? {
return experiments.firstOrNull { it.name == descriptor.name }
}
@@ -70,20 +94,38 @@ internal class ExperimentEvaluator(private val valuesProvider: ValuesProvider =
return (checksum % MAX_BUCKET).toInt()
}

/**
* Overrides a specified experiment
*
* @param context context
* @param descriptor descriptor of the experiment
* @param active overridden value for the experiment, true to activate it, false to deactivate
*/
fun setOverride(context: Context, descriptor: ExperimentDescriptor, active: Boolean) {
context.getSharedPreferences(OVERRIDES_PREF_NAME, Context.MODE_PRIVATE)
.edit()
.putBoolean(descriptor.name, active)
.apply()
}

/**
* Clears an override for a specified experiment
*
* @param context context
* @param descriptor descriptor of the experiment
*/
fun clearOverride(context: Context, descriptor: ExperimentDescriptor) {
context.getSharedPreferences(OVERRIDES_PREF_NAME, Context.MODE_PRIVATE)
.edit()
.remove(descriptor.name)
.apply()
}

/**
* Clears all experiment overrides
*
* @param context context
*/
fun clearAllOverrides(context: Context) {
context.getSharedPreferences(OVERRIDES_PREF_NAME, Context.MODE_PRIVATE)
.edit()
@@ -8,6 +8,12 @@ package mozilla.components.service.fretboard
* Represents an experiment sync result
*/
data class ExperimentsSnapshot(
/**
* Downloaded list of experiments
*/
val experiments: List<Experiment>,
/**
* Last time experiments were modified on the server, as a UNIX timestamp
*/
val lastModified: Long?
)
@@ -9,8 +9,9 @@ import android.content.Context
/**
* Entry point of the library
*
* @param source experiment remote source
* @param storage experiment local storage mechanism
* @property source experiment remote source
* @property storage experiment local storage mechanism
* @param valuesProvider provider for the device's values
*/
class Fretboard(
private val source: ExperimentSource,
@@ -103,6 +104,7 @@ class Fretboard(
/**
* Overrides a specified experiment
*
* @param context context
* @param descriptor descriptor of the experiment
* @param active overridden value for the experiment, true to activate it, false to deactivate
*/
@@ -113,6 +115,7 @@ class Fretboard(
/**
* Clears an override for a specified experiment
*
* @param context context
* @param descriptor descriptor of the experiment
*/
fun clearOverride(context: Context, descriptor: ExperimentDescriptor) {
@@ -55,6 +55,7 @@ class JSONExperimentParser {
* Converts the specified experiment to json
*
* @param experiment experiment to convert
*
* @return json representation of the experiment
*/
fun toJson(experiment: Experiment): JSONObject {
@@ -13,6 +13,8 @@ import java.util.concurrent.TimeUnit
/**
* Class used to schedule sync of experiment
* configuration from the server
*
* @param context context
*/
class JobSchedulerSyncScheduler(context: Context) {
private val jobScheduler = context.getSystemService(Context.JOB_SCHEDULER_SERVICE) as JobScheduler
@@ -30,6 +32,7 @@ class JobSchedulerSyncScheduler(context: Context) {
* Schedule sync with the default constraints
* (once a day)
*
* @param jobId unique identifier of the job
* @param serviceName object with the service to run
*/
fun schedule(jobId: Int, serviceName: ComponentName) {
@@ -9,6 +9,9 @@ import android.app.job.JobService
import mozilla.components.service.fretboard.Fretboard
import java.util.concurrent.Executors

/**
* JobScheduler job used to updating the list of experiments
*/
abstract class SyncJob : JobService() {
private val executor = Executors.newSingleThreadExecutor()

@@ -18,6 +18,7 @@ interface HttpClient {
*
* @param url destination url
* @param headers headers to submit with the request
*
* @return HTTP response
*/
fun get(url: URL, headers: Map<String, String>? = null): String
@@ -9,11 +9,11 @@ import java.net.URL
/**
* Helper class to make it easier to interact with Kinto
*
* @param httpClient http client to use
* @param baseUrl Kinto server url
* @param bucketName name of the bucket to fetch
* @param collectionName name of the collection to fetch
* @param headers headers to provide along with the request
* @property httpClient http client to use
* @property baseUrl Kinto server url
* @property bucketName name of the bucket to fetch
* @property collectionName name of the collection to fetch
* @property headers headers to provide along with the request
*/
internal class KintoClient(
private val httpClient: HttpClient = HttpURLConnectionHttpClient(),
@@ -35,7 +35,8 @@ internal class KintoClient(
/**
* Performs a diff, given the last_modified time
*
* @param lastModified last modified time
* @param lastModified last modified time as a UNIX timestamp
*
* @return Kinto diff response
*/
fun diff(lastModified: Long): String {
@@ -15,9 +15,10 @@ import org.json.JSONObject
* Class responsible for fetching and
* parsing experiments from a Kinto server
*
* @param baseUrl Kinto server url
* @param bucketName name of the bucket to fetch
* @param collectionName name of the collection to fetch
* @property baseUrl Kinto server url
* @property bucketName name of the bucket to fetch
* @property collectionName name of the collection to fetch
* @property client http client to use
*/
class KintoExperimentSource(
private val baseUrl: String,
@@ -20,7 +20,8 @@ internal class ExperimentsSerializer {
* Transforms the given list of experiments to
* its json file representation
*
* @param snapshot experiments to serialize
* @param snapshot experiment snapshot to serialize
*
* @return json file representation of the given experiments
*/
fun toJson(snapshot: ExperimentsSnapshot): String {
@@ -39,7 +40,8 @@ internal class ExperimentsSerializer {
* representation, as stored locally inside a file
*
* @param json json file contents
* @return list of experiments
*
* @return experiment snapshot with the parsed list of experiments
*/
fun fromJson(json: String): ExperimentsSnapshot {
val experimentsJson = JSONObject(json)
@@ -10,6 +10,11 @@ import mozilla.components.service.fretboard.ExperimentsSnapshot
import java.io.FileNotFoundException
import java.io.File

/**
* Class which uses a flat JSON file as an experiment storage mechanism
*
* @param file file where to store experiments
*/
class FlatFileExperimentStorage(file: File) : ExperimentStorage {
private val atomicFile: AtomicFile = AtomicFile(file)

0 comments on commit c874c34

Please sign in to comment.
You can’t perform that action at this time.