Skip to content
Branch: master
Find file History
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
..
Failed to load latest commit information.
src
README.md
build.gradle
proguard-rules.pro

README.md

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/
You can’t perform that action at this time.