Start adding javadoc on public api of the SDK and move some files.

This commit is contained in:
ganfra 2019-01-18 16:26:17 +01:00
parent 9914939045
commit 57db4086cb
42 changed files with 264 additions and 35 deletions

View file

@ -18,7 +18,7 @@
package im.vector.riotredesign.features.home.room.detail.timeline
import im.vector.matrix.android.api.session.events.model.TimelineEvent
import im.vector.matrix.android.api.session.room.timeline.TimelineEvent
class DefaultItemFactory {

View file

@ -23,7 +23,7 @@ import android.text.util.Linkify
import im.vector.matrix.android.api.permalinks.MatrixLinkify
import im.vector.matrix.android.api.permalinks.MatrixPermalinkSpan
import im.vector.matrix.android.api.session.events.model.EventType
import im.vector.matrix.android.api.session.events.model.TimelineEvent
import im.vector.matrix.android.api.session.room.timeline.TimelineEvent
import im.vector.matrix.android.api.session.events.model.toModel
import im.vector.matrix.android.api.session.room.model.MessageContent
import im.vector.riotredesign.core.extensions.localDateTime

View file

@ -19,7 +19,7 @@
package im.vector.riotredesign.features.home.room.detail.timeline
import android.text.TextUtils
import im.vector.matrix.android.api.session.events.model.TimelineEvent
import im.vector.matrix.android.api.session.room.timeline.TimelineEvent
import im.vector.matrix.android.api.session.events.model.toModel
import im.vector.matrix.android.api.session.room.model.Membership
import im.vector.matrix.android.api.session.room.model.RoomMember

View file

@ -19,7 +19,7 @@
package im.vector.riotredesign.features.home.room.detail.timeline
import android.text.TextUtils
import im.vector.matrix.android.api.session.events.model.TimelineEvent
import im.vector.matrix.android.api.session.room.timeline.TimelineEvent
import im.vector.matrix.android.api.session.events.model.toModel
import im.vector.matrix.android.api.session.room.model.RoomNameContent
import im.vector.riotredesign.R

View file

@ -19,7 +19,7 @@
package im.vector.riotredesign.features.home.room.detail.timeline
import android.text.TextUtils
import im.vector.matrix.android.api.session.events.model.TimelineEvent
import im.vector.matrix.android.api.session.room.timeline.TimelineEvent
import im.vector.matrix.android.api.session.events.model.toModel
import im.vector.matrix.android.api.session.room.model.RoomTopicContent
import im.vector.riotredesign.R

View file

@ -21,7 +21,7 @@ package im.vector.riotredesign.features.home.room.detail.timeline
import com.airbnb.epoxy.EpoxyAsyncUtil
import com.airbnb.epoxy.EpoxyModel
import im.vector.matrix.android.api.session.events.model.EventType
import im.vector.matrix.android.api.session.events.model.TimelineEvent
import im.vector.matrix.android.api.session.room.timeline.TimelineEvent
import im.vector.matrix.android.api.session.room.timeline.TimelineData
import im.vector.riotredesign.core.extensions.localDateTime
import im.vector.riotredesign.features.home.LoadingItemModel_

View file

@ -20,7 +20,7 @@ package im.vector.riotredesign.features.home.room.detail.timeline
import com.airbnb.epoxy.EpoxyModel
import im.vector.matrix.android.api.session.events.model.EventType
import im.vector.matrix.android.api.session.events.model.TimelineEvent
import im.vector.matrix.android.api.session.room.timeline.TimelineEvent
class TimelineItemFactory(private val messageItemFactory: MessageItemFactory,
private val roomNameItemFactory: RoomNameItemFactory,

View file

@ -16,7 +16,7 @@
*
*/
package im.vector.matrix.android.api.thread;
package im.vector.matrix.android;
import android.os.Handler;
import android.os.Looper;

View file

@ -23,7 +23,7 @@ import androidx.test.annotation.UiThreadTest
import com.zhuinden.monarchy.Monarchy
import im.vector.matrix.android.InstrumentedTest
import im.vector.matrix.android.LiveDataTestObserver
import im.vector.matrix.android.api.thread.MainThreadExecutor
import im.vector.matrix.android.MainThreadExecutor
import im.vector.matrix.android.internal.session.room.members.RoomMemberExtractor
import im.vector.matrix.android.internal.session.room.timeline.DefaultTimelineService
import im.vector.matrix.android.internal.session.room.timeline.TimelineBoundaryCallback

View file

@ -18,8 +18,8 @@
package im.vector.matrix.android.api
import androidx.lifecycle.ProcessLifecycleOwner
import android.content.Context
import androidx.lifecycle.ProcessLifecycleOwner
import com.zhuinden.monarchy.Monarchy
import im.vector.matrix.android.api.auth.Authenticator
import im.vector.matrix.android.api.session.Session
@ -32,7 +32,11 @@ import im.vector.matrix.android.internal.util.BackgroundDetectionObserver
import org.koin.standalone.inject
import java.util.concurrent.atomic.AtomicBoolean
/**
* This is the main entry point to the matrix sdk.
* This class is automatically init by a provider.
* To get the singleton instance, use getInstance static method.
*/
class Matrix private constructor(context: Context) : MatrixKoinComponent {
private val authenticator by inject<Authenticator>()

View file

@ -18,12 +18,24 @@
package im.vector.matrix.android.api
/**
* Generic callback interface for asynchronously.
* @param <T> the type of data to return on success
*/
interface MatrixCallback<in T> {
/**
* On success method, default to no-op
* @param data the data successfuly returned from the async function
*/
fun onSuccess(data: T) {
//no-op
}
/**
* On failure method, default to no-op
* @param failure the failure data returned from the async function
*/
fun onFailure(failure: Throwable) {
//no-op
}

View file

@ -23,12 +23,32 @@ import im.vector.matrix.android.api.auth.data.HomeServerConnectionConfig
import im.vector.matrix.android.api.session.Session
import im.vector.matrix.android.api.util.Cancelable
/**
* This interface defines methods to authenticate to a matrix server.
*/
interface Authenticator {
/**
* @param homeServerConnectionConfig this param is used to configure the Homeserver
* @param login the login field
* @param password the password field
* @param callback the matrix callback on which you'll receive the result of authentication.
* @return return a [Cancelable]
*/
fun authenticate(homeServerConnectionConfig: HomeServerConnectionConfig, login: String, password: String, callback: MatrixCallback<Session>): Cancelable
//TODO remove this method. Shouldn't be managed like that.
/**
* Check if there is an active [Session].
* @return true if there is at least one active session.
*/
fun hasActiveSessions(): Boolean
//TODO remove this method. Shouldn't be managed like that.
/**
* Get the last active [Session], if there is an active session.
* @return the lastActive session if any, or null
*/
fun getLastActiveSession(): Session?

View file

@ -21,6 +21,11 @@ package im.vector.matrix.android.api.auth.data
import com.squareup.moshi.Json
import com.squareup.moshi.JsonClass
/**
* This data class hold credentials user data.
* You shouldn't have to instantiate it.
* The access token should be use to authenticate user in all server requests.
*/
@JsonClass(generateAdapter = true)
data class Credentials(
@Json(name = "user_id") val userId: String,

View file

@ -20,10 +20,16 @@ package im.vector.matrix.android.api.auth.data
import android.net.Uri
import com.squareup.moshi.JsonClass
import im.vector.matrix.android.api.auth.data.HomeServerConnectionConfig.Builder
import im.vector.matrix.android.internal.network.ssl.Fingerprint
import okhttp3.CipherSuite
import okhttp3.TlsVersion
/**
* This data class holds how to connect to a specific Homeserver.
* It's used with [im.vector.matrix.android.api.auth.Authenticator] class.
* You should use the [Builder] to create one.
*/
@JsonClass(generateAdapter = true)
data class HomeServerConnectionConfig(
val homeServerUri: Uri,
@ -38,6 +44,9 @@ data class HomeServerConnectionConfig(
val forceUsageTlsVersions: Boolean = false
) {
/**
* This builder should be use to create a [HomeServerConnectionConfig] instance.
*/
class Builder {
private lateinit var homeServerUri: Uri

View file

@ -18,6 +18,10 @@
package im.vector.matrix.android.api.auth.data
/**
* This data class holds necessary data to open a session.
* You don't have to manually instantiate it.
*/
data class SessionParams(
val credentials: Credentials,
val homeServerConnectionConfig: HomeServerConnectionConfig

View file

@ -20,8 +20,16 @@ package im.vector.matrix.android.api.failure
import java.io.IOException
/**
* This class allows to expose differents kind of error to be then handled by the application.
* As it is a sealed class, you typically use it like that :
* when(failure) {
* is NetworkConnection -> Unit
* is ServerError -> Unit
* is Unknown -> Unit
* }
*/
sealed class Failure(cause: Throwable? = null) : Throwable(cause = cause) {
data class Unknown(val throwable: Throwable? = null) : Failure(throwable)
data class NetworkConnection(val ioException: IOException? = null) : Failure(ioException)
data class ServerError(val error: MatrixError) : Failure(RuntimeException(error.toString()))

View file

@ -21,6 +21,10 @@ package im.vector.matrix.android.api.failure
import com.squareup.moshi.Json
import com.squareup.moshi.JsonClass
/**
* This data class holds the error defined by the matrix specifications.
* You shouldn't have to instantiate it.
*/
@JsonClass(generateAdapter = true)
data class MatrixError(
@Json(name = "errcode") val code: String,

View file

@ -24,6 +24,10 @@ import android.text.method.LinkMovementMethod
import android.widget.TextView
import im.vector.matrix.android.api.MatrixPatterns
/**
* MatrixLinkify take a piece of text and turns all of the
* matrix patterns matches in the text into clickable links.
*/
object MatrixLinkify {
/**
@ -75,7 +79,10 @@ object MatrixLinkify {
}
}
/**
* Add linkMovementMethod on textview if not already set
* @param textView the textView on which the movementMethod is set
*/
fun addLinkMovementMethod(textView: TextView) {
val movementMethod = textView.movementMethod
if (movementMethod == null || movementMethod !is LinkMovementMethod) {

View file

@ -21,6 +21,11 @@ package im.vector.matrix.android.api.permalinks
import android.text.style.ClickableSpan
import android.view.View
/**
* This MatrixPermalinkSpan is a clickable span which use a [Callback] to communicate back.
* @param url the permalink url tied to the span
* @param callback the callback to use.
*/
class MatrixPermalinkSpan(private val url: String,
private val callback: Callback? = null) : ClickableSpan() {

View file

@ -20,6 +20,10 @@ package im.vector.matrix.android.api.permalinks
import android.net.Uri
/**
* This sealed class represents all the permalink cases.
* You don't have to instantiate yourself but should use [PermalinkParser] instead.
*/
sealed class PermalinkData {
data class EventLink(val roomIdOrAlias: String, val eventId: String) : PermalinkData()

View file

@ -22,7 +22,7 @@ import android.text.TextUtils
import im.vector.matrix.android.api.session.events.model.Event
/**
* Useful methods to deals with Matrix permalink
* Useful methods to create Matrix permalink.
*/
object PermalinkFactory {

View file

@ -21,13 +21,22 @@ package im.vector.matrix.android.api.permalinks
import android.net.Uri
import im.vector.matrix.android.api.MatrixPatterns
/**
* This class turns an uri to a [PermalinkData]
*/
object PermalinkParser {
/**
* Turns an uri string to a [PermalinkData]
*/
fun parse(uriString: String): PermalinkData {
val uri = Uri.parse(uriString)
return parse(uri)
}
/**
* Turns an uri to a [PermalinkData]
*/
fun parse(uri: Uri): PermalinkData {
val fragment = uri.fragment
if (fragment.isNullOrEmpty()) {

View file

@ -23,20 +23,44 @@ import im.vector.matrix.android.api.auth.data.SessionParams
import im.vector.matrix.android.api.session.group.GroupService
import im.vector.matrix.android.api.session.room.RoomService
/**
* This interface defines interactions with a session.
* An instance of a session will be provided by the SDK.
*/
interface Session : RoomService, GroupService {
/**
* The params associated to the session
*/
val sessionParams: SessionParams
/**
* This method allow to open a session. It does start some service on the background.
*/
@MainThread
fun open()
/**
* This method allow to close a session. It does stop some services.
*/
@MainThread
fun close()
/**
* Add a listener to the session.
* @param listener the listener to add.
*/
fun addListener(listener: Listener)
/**
* Remove a listener from the session.
* @param listener the listener to remove.
*/
fun removeListener(listener: Listener)
/**
* A global session listener to get notified for some events.
*/
// Not used at the moment
interface Listener

View file

@ -26,6 +26,9 @@ import java.lang.reflect.ParameterizedType
typealias Content = Map<String, @JvmSuppressWildcards Any>
/**
* This methods is a facility method to map a json content to a model.
*/
inline fun <reified T> Content?.toModel(): T? {
return this?.let {
val moshi = MoshiProvider.providesMoshi()
@ -34,6 +37,10 @@ inline fun <reified T> Content?.toModel(): T? {
}
}
/**
* Generic event class with all possible fields for events.
* The content and prevContent json fields can easily be mapped to a model with [toModel] method.
*/
@JsonClass(generateAdapter = true)
data class Event(
@Json(name = "type") val type: String,
@ -49,6 +56,10 @@ data class Event(
) {
/**
* Check if event is a state event.
* @return true if event is state event.
*/
fun isStateEvent(): Boolean {
return EventType.isStateEvent(type)
}

View file

@ -19,6 +19,9 @@
package im.vector.matrix.android.api.session.events.model
/**
* Constants defining known event types from Matrix specifications.
*/
object EventType {
const val PRESENCE = "m.presence"

View file

@ -18,6 +18,9 @@
package im.vector.matrix.android.api.session.group
/**
* This interface defines methods to interact within a group.
*/
interface Group {
val groupId: String
}

View file

@ -21,9 +21,22 @@ package im.vector.matrix.android.api.session.group
import androidx.lifecycle.LiveData
import im.vector.matrix.android.api.session.group.model.GroupSummary
/**
* This interface defines methods to get groups. It's implemented at the session level.
*/
interface GroupService {
/**
* Get a group from a groupId
* @param groupId the groupId to look for.
* @return the group with groupId or null
*/
fun getGroup(groupId: String): Group?
/**
* Get a live list of group summaries. This list is refreshed as soon as the data changes.
* @return the [LiveData] of [GroupSummary]
*/
fun liveGroupSummaries(): LiveData<List<GroupSummary>>
}

View file

@ -21,17 +21,34 @@ package im.vector.matrix.android.api.session.room
import androidx.lifecycle.LiveData
import im.vector.matrix.android.api.session.room.model.MyMembership
import im.vector.matrix.android.api.session.room.model.RoomSummary
import im.vector.matrix.android.api.session.room.send.SendService
import im.vector.matrix.android.api.session.room.timeline.TimelineService
import im.vector.matrix.android.api.util.Cancelable
/**
* This interface defines methods to interact within a room.
*/
interface Room : TimelineService, SendService {
/**
* The roomId of this room
*/
val roomId: String
/**
* The membership of this room for the current user
*/
val myMembership: MyMembership
/**
* A live [RoomSummary] associated with the room
*/
val roomSummary: LiveData<RoomSummary>
/**
* This methods load all room members if it was done yet.
* @return a [Cancelable]
*/
fun loadRoomMembersIfNeeded(): Cancelable
}

View file

@ -21,10 +21,22 @@ package im.vector.matrix.android.api.session.room
import androidx.lifecycle.LiveData
import im.vector.matrix.android.api.session.room.model.RoomSummary
/**
* This interface defines methods to get rooms. It's implemented at the session level.
*/
interface RoomService {
/**
* Get a room from a roomId
* @param roomId the roomId to look for.
* @return the room with roomId or null
*/
fun getRoom(roomId: String): Room?
/**
* Get a live list of room summaries. This list is refreshed as soon as the data changes.
* @return the [LiveData] of [RoomSummary]
*/
fun liveRoomSummaries(): LiveData<List<RoomSummary>>
}

View file

@ -16,14 +16,23 @@
*
*/
package im.vector.matrix.android.api.session.room
package im.vector.matrix.android.api.session.room.send
import im.vector.matrix.android.api.MatrixCallback
import im.vector.matrix.android.api.session.events.model.Event
import im.vector.matrix.android.api.util.Cancelable
/**
* This interface defines methods to send events in a room. It's implemented at the room level.
*/
interface SendService {
/**
* Method to send a text message asynchronously.
* @param text the text message to send
* @param callback the callback to be notified.
* @return a [Cancelable]
*/
fun sendTextMessage(text: String, callback: MatrixCallback<Event>): Cancelable

View file

@ -19,10 +19,25 @@
package im.vector.matrix.android.api.session.room.timeline
import androidx.paging.PagedList
import im.vector.matrix.android.api.session.events.model.TimelineEvent
/**
* This data class is a holder for timeline data.
* It's returned by [TimelineService]
*/
data class TimelineData(
/**
* The [PagedList] of [TimelineEvent] to usually be render in a RecyclerView.
*/
val events: PagedList<TimelineEvent>,
/**
* True if Timeline is currently paginating forward on server
*/
val isLoadingForward: Boolean = false,
/**
* True if Timeline is currently paginating backward on server
*/
val isLoadingBackward: Boolean = false
)

View file

@ -16,10 +16,16 @@
*
*/
package im.vector.matrix.android.api.session.events.model
package im.vector.matrix.android.api.session.room.timeline
import im.vector.matrix.android.api.session.events.model.Event
import im.vector.matrix.android.api.session.room.model.RoomMember
/**
* This data class is a wrapper around an Event. It allows to get useful data in the context of a timeline.
* This class is used by [TimelineService] through [TimelineData]
* Users can also enrich it with metadata.
*/
data class TimelineEvent(
val root: Event,
val localId: String,
@ -28,6 +34,12 @@ data class TimelineEvent(
val metadata = HashMap<String, Any>()
/**
* The method to enrich this timeline event.
* If you provides multiple data with the same key, only first one will be kept.
* @param key the key to associate data with.
* @param data the data to enrich with.
*/
fun enrichWith(key: String?, data: Any?) {
if (key == null || data == null) {
return
@ -37,6 +49,11 @@ data class TimelineEvent(
}
}
/**
* Get the metadata associated with a key.
* @param key the key to get the metadata
* @return the metadata
*/
inline fun <reified T> getMetadata(key: String): T? {
return metadata[key] as T?
}

View file

@ -16,9 +16,8 @@
*
*/
package im.vector.matrix.android.api.session.events.interceptor
package im.vector.matrix.android.api.session.room.timeline
import im.vector.matrix.android.api.session.events.model.TimelineEvent
interface TimelineEventInterceptor {

View file

@ -20,8 +20,18 @@ package im.vector.matrix.android.api.session.room.timeline
import androidx.lifecycle.LiveData
/**
* This interface defines methods to interact with the timeline. It's implemented at the room level.
*/
interface TimelineService {
/**
* This is the main method of the service. It allows to listen for live [TimelineData].
* It's automatically refreshed as soon as timeline data gets updated, through sync or pagination.
*
* @param eventId: an optional eventId to start loading timeline around.
* @return the [LiveData] of [TimelineData]
*/
fun timeline(eventId: String? = null): LiveData<TimelineData>
}

View file

@ -18,7 +18,15 @@
package im.vector.matrix.android.api.util
/**
* An interface defining a unique cancel method.
* It should be used with methods you want to be able to cancel, such as ones interacting with Web Services.
*/
interface Cancelable {
/**
* The cancel method, it does nothing by default.
*/
fun cancel() {
//no-op
}

View file

@ -24,7 +24,7 @@ import com.zhuinden.monarchy.Monarchy
import im.vector.matrix.android.api.MatrixCallback
import im.vector.matrix.android.api.session.events.model.Event
import im.vector.matrix.android.api.session.room.Room
import im.vector.matrix.android.api.session.room.SendService
import im.vector.matrix.android.api.session.room.send.SendService
import im.vector.matrix.android.api.session.room.model.Membership
import im.vector.matrix.android.api.session.room.model.MyMembership
import im.vector.matrix.android.api.session.room.model.RoomSummary
@ -36,7 +36,6 @@ import im.vector.matrix.android.internal.database.model.RoomSummaryEntity
import im.vector.matrix.android.internal.database.model.RoomSummaryEntityFields
import im.vector.matrix.android.internal.database.query.where
import im.vector.matrix.android.internal.di.MatrixKoinComponent
import im.vector.matrix.android.internal.session.SessionListeners
import im.vector.matrix.android.internal.session.room.members.LoadRoomMembersTask
import im.vector.matrix.android.internal.task.TaskExecutor
import im.vector.matrix.android.internal.task.configureWith

View file

@ -19,8 +19,8 @@
package im.vector.matrix.android.internal.session.room
import im.vector.matrix.android.api.auth.data.SessionParams
import im.vector.matrix.android.api.session.room.SendService
import im.vector.matrix.android.api.session.room.send.EventFactory
import im.vector.matrix.android.api.session.room.send.SendService
import im.vector.matrix.android.internal.session.room.send.EventFactory
import im.vector.matrix.android.api.session.room.timeline.TimelineService
import im.vector.matrix.android.internal.session.DefaultSession
import im.vector.matrix.android.internal.session.room.members.DefaultLoadRoomMembersTask

View file

@ -30,7 +30,6 @@ import im.vector.matrix.android.internal.database.model.EventEntity
import im.vector.matrix.android.internal.database.query.where
import im.vector.matrix.android.internal.di.MatrixKoinComponent
import im.vector.matrix.android.internal.util.WorkerParamsFactory
import im.vector.matrix.android.internal.util.tryTransactionAsync
import im.vector.matrix.android.internal.util.tryTransactionSync
import io.realm.Realm
import org.koin.standalone.inject

View file

@ -22,8 +22,7 @@ import androidx.work.*
import com.zhuinden.monarchy.Monarchy
import im.vector.matrix.android.api.MatrixCallback
import im.vector.matrix.android.api.session.events.model.Event
import im.vector.matrix.android.api.session.room.SendService
import im.vector.matrix.android.api.session.room.send.EventFactory
import im.vector.matrix.android.api.session.room.send.SendService
import im.vector.matrix.android.api.util.Cancelable
import im.vector.matrix.android.internal.database.helper.add
import im.vector.matrix.android.internal.database.helper.updateDisplayIndexes

View file

@ -16,7 +16,7 @@
*
*/
package im.vector.matrix.android.api.session.room.send
package im.vector.matrix.android.internal.session.room.send
import im.vector.matrix.android.api.auth.data.Credentials
import im.vector.matrix.android.api.session.events.model.Content

View file

@ -22,8 +22,8 @@ import androidx.lifecycle.LiveData
import androidx.paging.LivePagedListBuilder
import androidx.paging.PagedList
import com.zhuinden.monarchy.Monarchy
import im.vector.matrix.android.api.session.events.interceptor.TimelineEventInterceptor
import im.vector.matrix.android.api.session.events.model.TimelineEvent
import im.vector.matrix.android.api.session.room.timeline.TimelineEventInterceptor
import im.vector.matrix.android.api.session.room.timeline.TimelineEvent
import im.vector.matrix.android.api.session.room.timeline.TimelineData
import im.vector.matrix.android.api.session.room.timeline.TimelineService
import im.vector.matrix.android.internal.database.mapper.asDomain

View file

@ -22,7 +22,7 @@ import androidx.lifecycle.LiveData
import androidx.paging.PagedList
import com.zhuinden.monarchy.Monarchy
import im.vector.matrix.android.api.MatrixCallback
import im.vector.matrix.android.api.session.events.model.TimelineEvent
import im.vector.matrix.android.api.session.room.timeline.TimelineEvent
import im.vector.matrix.android.internal.database.model.ChunkEntity
import im.vector.matrix.android.internal.database.query.findIncludingEvent
import im.vector.matrix.android.internal.task.TaskExecutor