Skip to content

android-guide.md

Latest commit

 

History

History
216 lines (162 loc) · 7.61 KB

android-guide.md

File metadata and controls

216 lines (162 loc) · 7.61 KB
Raw

JNexus Android App Guide

Back to Getting Started | Configuration

Overview

The JNexus Android app provides full Nexus repository management on Android devices. Built with Jetpack Compose and Material Design 3, it offers a native Android experience with secure credential storage via AES-256 encryption.

System Requirements

  • Android 8.0 (API 26) or higher
  • Internet access to your Nexus server

Installation

From GitHub Releases

  1. Download the latest APK from GitHub Releases
  2. On your Android device, enable "Install from Unknown Sources" in Settings > Security
  3. Open the downloaded APK file
  4. Tap "Install"
  5. Open the app

Build from Source

git clone https://github.com/FlossWare/nexus-java.git
cd nexus-java

# Build debug APK
./gradlew :jnexus-android:assembleDebug

# Install on connected device
adb install jnexus-android/build/outputs/apk/debug/jnexus-android-debug.apk

First Launch

Step 1: Configure Credentials

  1. Open the app
  2. Tap the Settings tab (bottom navigation)
  3. Enter your Nexus server details:
    • URL: Your Nexus server address (e.g., https://nexus.example.com)
    • Username: Your Nexus account
    • Password: Your password or user token
  4. Optionally configure:
    • Repositories: Comma-separated list (e.g., maven-releases,maven-snapshots)
    • Default repository: Pre-selected repository on startup
    • Default regex: Pre-filled filter pattern
    • Default dry-run: Whether dry-run is enabled by default
    • HTTP timeout: Connection timeout in seconds (default: 30)
  5. Tap Save
  6. Credentials are encrypted with AES-256-GCM and stored in EncryptedSharedPreferences

Step 2: List Components

  1. Tap the List tab
  2. Select a repository from the dropdown
  3. Tap List (cached) or Refresh (fresh from server)
  4. Components appear as cards showing name, size, and creation date

Screens

List Screen

The main screen for browsing and managing components.

Features:

  • Repository dropdown (ExposedDropdownMenuBox): Select from configured repositories
  • List button: Fetch components using cache (fast)
  • Refresh button: Fetch components bypassing cache (always fresh)
  • Component cards: Each card shows component ID, file size, and path
  • Tap card: View full component metadata (content type, format, dates, checksum)
  • Delete: Each card has a delete option with confirmation dialog
  • Error display: Connection or authentication errors shown in a red card

Gestures:

  • Tap a component card to view its full details
  • Pull down to refresh the component list

Search Screen

Advanced filtering for finding specific components.

Features:

  • Repository selector: Choose which repository to search
  • Size range filters: Minimum and maximum size in bytes
  • Date range filters: Created after/before dates (ISO 8601 format)
  • File extension filter: Filter by extension (e.g., .jar)
  • Regex filter: Path pattern matching
  • Collapsible sections: Filter categories expand/collapse with AnimatedVisibility
  • Clear filters: Reset all filter values

Usage:

  1. Select a repository
  2. Set one or more filters
  3. Tap Search
  4. Results show only matching components

Stats Screen

Repository analytics and statistics.

Features:

  • Overview section: Total components, total size (MB/GB), average size, median size
  • Size distribution: 5 size buckets with component counts
    • < 1 MB
    • 1 MB - 10 MB
    • 10 MB - 100 MB
    • 100 MB - 1 GB

    • 1 GB

  • File type breakdown: Sorted by total size per extension
  • Age distribution: Components grouped by age (last 7/30/90 days, older)
  • Largest components: Top 10 components sorted by size

Usage:

  1. Select a repository
  2. Tap Calculate Statistics
  3. Scroll through the analytics cards

Settings Screen

Credential and configuration management.

Features:

  • Nexus URL: Server address input
  • Username: Account name input
  • Password: Secure input with show/hide toggle (PasswordVisualTransformation)
  • Repository list: Comma-separated list of repository names
  • Default values: Pre-fill options for other screens
  • HTTP timeout: Connection timeout in seconds
  • Save button: Encrypt and store all settings
  • Clear button: Remove all stored credentials and settings
  • Security info: Card explaining AES-256-GCM encryption

Security:

  • Passwords are encrypted using EncryptedSharedPreferences
  • Master key generated by Android Keystore with AES256_GCM scheme
  • Keys encrypted with AES256_SIV
  • Values encrypted with AES256_GCM
  • Stored in private app directory, inaccessible to other apps

Navigation

The app uses bottom navigation with 4 tabs:

Tab Icon Description
List List icon Browse and manage components
Search Search icon Advanced filtering
Stats Chart icon Repository analytics
Settings Gear icon Credential and configuration

Architecture

The Android app shares the same business logic as the desktop version through the jnexus-core module:

  • NexusClientOkHttp: Uses OkHttp for HTTP communication (replaces java.net.http)
  • NexusService: Shared business logic from jnexus-core (filtering, statistics)
  • CredentialsAndroid: Encrypted credential storage
  • NexusApplication: Application-level dependency injection (singletons)

Tips and Tricks

  1. Use Refresh for accuracy: The List button uses cached data; use Refresh when you need current information
  2. Configure repositories: Adding a repository list in Settings enables the dropdown selector
  3. Check your URL: Make sure the Nexus URL uses HTTPS and does not have a trailing slash
  4. Password visibility: Use the eye icon to toggle password visibility when entering credentials
  5. Date format: Use ISO 8601 format for date filters: 2024-01-01T00:00:00Z

Troubleshooting

Issue Solution
Network error Check internet connection and Nexus URL
401 Unauthorized Verify username and password in Settings
Connection timeout Increase HTTP timeout in Settings (default: 30s)
App crashes on startup Clear app data: Settings > Apps > JNexus > Clear Data
Cannot install APK Enable "Install from Unknown Sources" in device settings
Slow performance Check network connection; large repositories take longer

Building from Source

Debug Build

./gradlew :jnexus-android:assembleDebug

Output: jnexus-android/build/outputs/apk/debug/jnexus-android-debug.apk

Release Build

./gradlew :jnexus-android:assembleRelease

Note: Requires signing configuration in gradle.properties or environment variables.

Running Tests

# Unit tests
./gradlew :jnexus-android:testDebugUnitTest

# Instrumented tests (requires device or emulator)
./gradlew :jnexus-android:connectedDebugAndroidTest

Video Tutorials

These video tutorials cover Android app workflows:

See the Video Tutorials catalog for all available tutorials.

Back to Getting Started | All Guides