tubestation/mobile/android/android-components/components/browser/session

Android Components > Browser > Session

This component provides a generic representation of a browser Session and a SessionManager to link browser sessions to underlying Engine Sessions, as well as a SessionStorage to persist and restore sessions.

Usage

Setting up the dependency

Use Gradle to download the library from maven.mozilla.org (Setup repository):

implementation "org.mozilla.components:browser-session:{latest-version}"

Session

Session is a value type representing the state of a browser session. Session instances are usually created by UseCase types in feature modules e.g. in AddNewTabUseCase.

val session = Session("https://mozilla.org")
val privateSession = Session("https://mozilla.org", private = true)

// Session instances provide access to numerous observable fields
val url = session.url
val title = session.title
val loadingProgress = session.progress
val securityInfo = session.securityInfo
// ...

// Changes to a session can be observed
session.register(object : Session.Observer {
    onUrlChanged(session: Session, url: String) {
    	// The session is pointing to the provided url now
    }
    onTitleChanged(session: Session, title: String) {
    	// The title of the page this session points to has changed
    }
    onProgress(session: Session, progress: Int)
    	// The page loading progress was updated
    }
    onSecurityChanged(session: Session, securityInfo: SecurityInfo) {
       // The security info of the session was updated
    }
    onTrackerBlocked() {
    	// A tracker was blocked for this session
    }
    // ...
})

SessionManager

SessionManager contains the core functionality of this component. It provides functionality to hold all active browser sessions and link them to their corresponding engine sessions. A SessionManager can be created by providing an Engine instance:

val sessionManager = SessionManager(engine)

// Sessions can be added and removed
val session = Session("https://mozilla.org")
sessionManager.add(session)
sessionManager.remove(session)
sessionManager.removeAll()

// Sessions can be selected (i.e. for switching tabs)
sessionManager.select(session)

// Sessions can be retrieved in various ways
val selectedSession = sessionManager.selectedSession
val sessions = sessionManager.sessions
val engineSession = sessionManager.getEngineSession(session) 
val selectedEngineSession = sessionManager.getEngineSession()

// Engine sessions can automatically be created if none exists for the provided session
val engineSession = sessionManager.getOrCreateEngineSession(session)
val selectedEngineSession = sessionManager.getOrCreateEngineSession()

// Changes to a SessionManager can be observed
sessionManager.register(object : SessionManager.Observer {
    onSessionSelected(session: Session) {
        // The provided session was selected. 
    }
    onSessionAdded(session: Session) {
    	// The provided session was added.
    }
    onSessionRemoved(session: Session) {
    	// The provided session was removed.
    }
    onAllSessionsRemoved() {
    	// The session manager has been cleared (removeAll has been called).
    }
})

SessionStorage

SessionStorage is an interface describing an abstract contract for session storage implementations. Other components reference this abstract type directly to allow for custom (application-provided) implementations. A default implementation is provided as part of this module, which persists browser and engine session states to a JSON file using an AtomicFile. A DefaultStorage instance can be created by providing the Android application context:

val sessionStorage = DefaultSessionStorage(applicationContext)

The feature-session component takes care of starting/stopping the session storage automatically. If the feature component is not being used the following API calls are available:

sessionStorage.start(sessionManager)
sessionStorage.stop()

Once started, session can be persisted and restored by providing a reference to the application's SessionManager:

sessionStorage.persist(sessionManager)
sessonStorage.restore(sessionManager)

License

This Source Code Form is subject to the terms of the Mozilla Public
License, v. 2.0. If a copy of the MPL was not distributed with this
file, You can obtain one at http://mozilla.org/MPL/2.0/