GeneLens

Cross-Platform Biological Data Aggregator & Orchestration Engine for Joint NCBI Entrez and UniProtKB Alignment

GeneLens is a desktop suite engineered in Java that harmonizes real-time genomic and proteomic metadata extraction. By combining automated relational parsing, deterministic query optimization, and thread-isolated asynchronous networking via SwingWorker components, it bridges the gap between the National Center for Biotechnology Information (NCBI) database APIs and the UniProt Knowledgebase (UniProtKB REST API). This application provides researchers with localized chromosome mappings, accession links, protein sequences, and structural annotations through an optimized, low-overhead graphical pipeline.

---

🚀 Features

• 🔗 Multi-Database Integration Fetches and merges data from NCBI and UniProt.

• 📦 Batch Processing Query multiple gene/protein identifiers in a single run.

• 🧠 Structured Data Visualization Displays gene details, protein sequences, functional annotations, and organism info.

• 📊 Real-Time Logging & Progress Tracking Non-blocking background execution with live logs.

• 📄 Export Support Export retrieved results as .txt files with selectable detail levels.

• 🧪 Sample Data Loader Preloaded examples for quick testing and demonstration.

• 🛡 Robust Error Handling Retry logic, safe JSON parsing, and user-friendly error messages.

---

EXECUTIVE OVERVIEW

In bioinformatics workflows, researchers routinely bridge cross-database information silos manually—transitioning between NCBI Gene repositories to locate genomic chromosomal positions, and UniProtKB to inspect structural protein characteristics and amino acid sequences. This manual cross-referencing introduces transcription errors, disrupts automated discovery pipelines, and limits bulk evaluation scalability.

GeneLens resolves this by implementing a structured data translation middleware layer. Given a biological identifier (e.g., standard gene symbols or protein accession codes) and an optional target organism constraint, the engine handles target mapping natively. It automatically encodes and coordinates cross-database search queries, handles rate limits using retry loops, and processes heterogeneous JSON metadata trees into uniform, immutable domain objects.

Business & Scientific Impact

• Eliminates Analysis Bottlenecks: Replaces single-query manual copy-and-paste tasks with an input vector topology, processing multiple multi-database operations concurrently.
• Guarantees High Reproducibility: Serializes raw structured API responses into deterministic data representations and flat text configurations, matching compliance profiles needed for clinical research and academic publications.
• Zero-Footprint Scalability: Engineered via pure Java low-overhead execution frames, removing the weight of heavy container runtimes while maintaining maximum memory configuration flexibility.

---

🛠 Installation & Setup

Prerequisites

Ensure the following are installed on your system:

• Java JDK 8 or higher
• IntelliJ IDEA (recommended) or any Java-compatible IDE
• Internet connection (required for NCBI & UniProt APIs)

---

Dependency: Gson (Required)

This project uses Google Gson for JSON parsing. ⚠️ gson.jar is NOT included in this repository and must be added manually.

Option 1: Download Gson JAR (Recommended)

1. Download the Gson JAR from:

https://github.com/google/gson

or from Maven Central

2. In IntelliJ IDEA:

• Open the project
• Go to File → Project Structure → Libraries
• Click + → Java
• Select the downloaded gson-*.jar
• Apply and close

---

Option 2: Using Maven (Optional)

If you convert the project to Maven, add the following dependency:

<dependency>
<groupId>com.google.code.gson</groupId>
<artifactId>gson</artifactId>
<version>2.10.1</version>
</dependency>

---

CORE FEATURES

Feature	Description	Technical Value	Real-World Impact
Multi-Threaded Asynchronous Aggregation	Offloads heavy I/O database API networking requests to an abstract background SwingWorker thread array, preserving 60 FPS rendering cycles on the Event Dispatch Thread (EDT).	Eliminates GUI lockouts or freeze states during multi-second remote server processing.	Researchers maintain UI responsiveness and can dynamically track query tasks in real time via an embedded log component.
Fail-Safe HTTP Client Engine	Implements a robust connection manager with configurable connection and read timeouts, backed by an autonomous retry mechanism (getWithRetry).	Mitigates intermittent remote API failure points by applying deterministic thread sleep blocks (5000ms) between retries.	Resilient to fluctuating network drops, eliminating the need to restart large batch queries manually.
Unified Biological Entity Mapper	Resolves unstructured target search strings into structured profiles by linking data from NCBI's E-Utilities and UniProt's KB REST endpoint.	Programmatically matches query predicates with target organism specifiers via conditional parameter encoding.	Accelerates target validation by instantly linking chromosomal locations to functional sequences.
Flexible Data Exporter Matrix	Provides a configurable data serialization interface supporting multi-tier selection profiles ("All Data", "Basic Info Only", "NCBI & UniProt", "Just Sequences").	Leverages native PrintWriter streams to safely compile data structures into standardized, structured text reports.	Facilitates downstream biological pipeline processing, such as feeding sequences into sequence alignment algorithms like BLAST.

---

SYSTEM ARCHITECTURE

GeneLens is structured using a variation of the MVC paradigm, explicitly separating UI views from remote REST query workers.

High-Level Data Flow Topology

graph TD
    A[MainApp UI Frame] -->|1. Triggers Action Event| B(Asynchronous SwingWorker)
    B -->|2. Reads Input Fields| C[EntryPanel Component Vector]
    B -->|3. Dispatches Identifiers| D[DBTranslate Translation Middleware]
    D -->|4a. Performs ESearch / ESummary| E[NCBI Entrez Gateway API]
    D -->|4b. Performs Search Query| F[UniProt REST Repository]
    E -->|5a. Return JSON Data| D
    F -->|5b. Return JSON Data| D
    D -->|6. Marshals via JsonParserUtil| G[ProteinGeneData Target Object]
    G -->|7. Pushes Model Dataset| H[ResultWindow Tab View]
    H -->|8. Serializes Selective Fields| I[FileExportUtil IO Stream] 

Loading

API Lifecycle and Sync Sequencing

The interaction lifecycle during data extraction ensures that the network stack does not choke the presentation layer, relying on thread isolation:

sequenceDiagram autonumber participant UI as MainApp (Event Dispatch Thread) participant Worker as SwingWorker Thread participant DB as DBTranslate Core Engine participant Net as HttpClientUtil HTTP Stack

UI->>Worker: execute() background task
activate Worker
UI->>UI: setFetchingState(true) & enable JProgressBar [Indeterminate]

Worker->>DB: translateData(identifier, organism)
activate DB

DB->>Net: getWithRetry(NCBI_Eutils_URL)
activate Net
Net-->>DB: Returns Search/Summary JSON String
deactivate Net

DB->>Net: getWithRetry(UniProt_REST_URL)
activate Net
Net-->>DB: Returns Functional/Sequence JSON String
deactivate Net

DB->>DB: processData() - cross-reference and deduplicate fields
DB-->>Worker: Returns fully populated ProteinGeneData object
deactivate DB

Worker-->>UI: done() callback dispatched to EDT
deactivate Worker
UI->>UI: Render ResultWindow Frame with Tabbing Topologies
UI->>UI: Reset progress indicator status to "Ready"

---

TECH STACK ANALYSIS

Architecture, Core Language & UI Framework

Technology	Category	Engineering Advantages	Why It Was Chosen
Java SE (JDK 11+)	Core Language & Runtime Environment	Standard, statically typed OOP platform with strong backwards compatibility and runtime optimization through the HotSpot JIT compiler.	Provides structural data types, compile-time type safety across business logic boundaries, and reliable Cross-Platform UI execution on Windows, macOS, and Linux systems.
Java Swing / AWT	Graphical User Interface Framework	Built-in, zero-dependency visual runtime framework using event-driven paradigms (ActionListener) and complex component layouts.	Eliminates heavy native system binary requirements or bloated rendering containers, ensuring quick application startup speeds and zero-footprint system resource overhead.

External Dependencies & Serializers

Dependency	Category	Engineering Advantages	Why It Was Chosen
Google Gson	JSON Parsing & Object-Relational Mapping	Dynamic tree-walking (JsonObject, JsonArray) and light parsing pipelines capable of streaming data straight to elements.	Efficiently processes deeply nested, variable schemas delivered by external Web REST endpoints without needing hardcoded object-mapping schemas for each distinct remote query type.

Remote Repositories & Data Source Interfaces

Target Endpoint	Category	Engineering Advantages	Why It Was Chosen
NCBI Entrez E-Utilities API	Genomic Database Gateway	Standardized biological server interface exposing precise database operations through web URLs (esearch.fcgi, esummary.fcgi).	Used to cross-reference biological identifiers against standardized NCBI Gene records and fetch verified gene descriptions or taxonomy codes.
UniProt KB REST API	Proteomic Knowledge Base	High-coverage protein indexing system providing programmatic lookups and rich structural details like functional descriptions and amino acid sequences.	Serves as the primary source for pulling precise, structured protein properties and continuous macromolecular sequence strings.

System Utilities & File I/O

Utility Module	Category	Engineering Advantages	Why It Was Chosen
HttpURLConnection Engine	Core Network Stack	Lightweight network handler built into standard library packages, supporting low-overhead request configurations and response code filtering.	Keeps the binary footprint small by avoiding heavy third-party HTTP clients while providing fine-grained control over connection rules and retry handling.
PrintWriter Serialization Core	Local File System Exporter	Fast, high-level file system adapter capable of managing character formatting and printing textual outputs straight to plain text files.	Safely writes organized datasets out to clean, local .txt records for easier parsing and reuse in downstream analysis tools.

CODEBASE INTELLIGENCE

Design Patterns & Software Architecture Paradigms

• Utility Encapsulation Pattern (Stateless Helper Strategy) The codebase cleanly separates foundational I/O and text formatting away from business workflow engines by using stateless utility classes. Classes such as HttpClientUtil and JsonParserUtil use public static execution boundaries, minimizing heap object allocations and ensuring thread-safe access to standard parsing and networking features across the application.
• Decoupled Model-View Separations (Variant MVC) The system maintains a clean separation of concerns by isolating data models, presentation components, and network operations:
  • Model: ProteinGeneData manages data states and object properties independently of how they are viewed or gathered.
  • View: MainApp, EntryPanel, and ResultWindow focus purely on UI rendering, user interaction fields, and action dispatching.
  • Controller/Service: DBTranslate orchestrates the conversion of raw inputs into enriched data objects by coordinating multi-source API queries.
• Static Configuration Provider Pattern Global execution details and API URLs are managed through a centralized properties matrix in Config.java. System properties are configured securely inside a thread-safe static initialization block, providing immutable, read-only setup configurations via global accessor interfaces:

  static {
      prop.setProperty("ncbi.email", "abc@google.com");
      prop.setProperty("ncbi.tool", "GeneLens");
      prop.setProperty("ncbi.baseurl", "[https://eutils.ncbi.nlm.nih.gov/entrez/eutils](https://eutils.ncbi.nlm.nih.gov/entrez/eutils)");
  }

• Asynchronous Processing Strategy (Worker-Thread Isolation) To keep the presentation layer performant and lag-free, the application avoids blocking operations on the primary Event Dispatch Thread (EDT). Heavy network I/O operations are offloaded to background threads using specialized SwingWorker implementations:

  SwingWorker<List<ProteinGeneData>, String> worker = new SwingWorker<>() {
      @Override
      protected List<ProteinGeneData> doInBackground() throws Exception {
          // High-latency network transactions executed on a isolated worker thread
      }
  };

Data Structure Diagnostics & Algorithmic Efficiency

• Order-Preserving Associative Arrays (LinkedHashMap) When managing genomic properties and proteomic features, the application chooses LinkedHashMap over a standard hash map:

  this.ncbiData = new LinkedHashMap<>();
  this.uniprotData = new LinkedHashMap<>();

  Engineering Advantage: This preserves the original order of properties returned by external REST endpoints. This ensures data remains structured consistently when viewed in UI tab grids or exported to text files, without requiring expensive sorting routines.
• Linear-Time Deduplication Strategy ($O(N)$ Complexity) When processing functional annotations across diverse databases, the engine prevents duplicate records by filtering listings through a temporary LinkedHashSet structure:

  Set<String> uniqueFuncs = new LinkedHashSet<>(data.getFunctions());
  data.getFunctions().clear();
  data.getFunctions().addAll(uniqueFuncs);

  Algorithmic Advantage: This deduplicates entries in linear time ($O(N)$) while maintaining the structural sequence of the original dataset, avoiding nested loop comparisons that drop performance to $O(N^2)$.
• Dynamic Component Vector Management User inputs are managed dynamically in MainApp using an ArrayList mapping strategy. This allows the user interface to scale on demand, adding or removing row panels smoothly as researchers adjust their query parameters.

Fault Isolation & Robust Error Management

• Defensive Parsing and Null-Safety Interceptors To safeguard against unpredictable payload changes from external APIs, the parsing utility wraps downstream extractions with null-safe fallback checks:

  public static String getString(JsonObject jsonObj, String key, String defaultValue) {
      if(jsonObj.has(key) && !jsonObj.get(key).isJsonNull())
          return jsonObj.get(key).getAsString();
      return defaultValue;
  }

  Engineering Advantage: This isolates the data conversion pipeline from variations in remote API responses, preventing unexpected NullPointerException crashes if specific attributes are missing.
• Non-Disruptive Error Encapsulation The system catches runtime failures gracefully during query execution, logging errors within the relevant data object instead of interrupting the entire app pipeline:

  catch(Exception e){
      data.setErrorMsg("Error : " + e.getMessage());
  }

  Engineering Advantage: This ensures that if a single record fails during batch operations, subsequent entries continue processing smoothly without crashing the active worker thread.
• Network Resilience and Safe Encoding The networking layer enforces strict connection and read timeouts (10000ms) to prevent application lockups from unresponsive remote servers. Additionally, inputs are systematically sanitized using UTF-8 URL encoding, ensuring queries containing spaces or special biological characters don't break network requests.

---

Why This Project Stands Out

• Production-Grade Concurrency & UI Stability Demonstrates advanced mastery of multi-threaded Java systems by implementing decoupling between the Event Dispatch Thread (EDT) and high-latency I/O operations via SwingWorker architectures. This architecture prevents application hanging or interface freezing, reflecting production-level design thinking expected of mid-to-senior backend and client engineers.

• Fault-Tolerant Distributed Integration Features specialized network orchestration utilities capable of programmatic parameter encoding, structured timeout enforcement (10000ms), and autonomous connection recovery streams (getWithRetry) with deterministic delay back-offs. This ensures enterprise reliability when interacting with complex, rate-limited external third-party microservices like the NCBI Entrez and UniProt KB REST gateways.

• Clean Architecture & Separation of Concerns Rejects low-quality monolithic scripting in favor of strict data encapsulation principles. Code patterns are clearly partitioned into single-responsibility tiers (bioapp.data, bioapp.ui, bioapp.utils), which ensures low coupling, streamlined debugging, and easy maintainability for cross-functional engineering teams.

• High Algorithmic Efficiency & Data Sanity Utilizes targeted collection types—such as ordered key-value lookup maps (LinkedHashMap) to maintain API data groupings without running expensive manual sorts, and dynamic linear-time ($O(N)$) hashing adapters (LinkedHashSet) to strip duplicate biological annotations. This demonstrates solid foundational knowledge of data structures and algorithms optimized to handle heavy data payloads cleanly.

• Immediate Research & Industry Utility Solves a real-world scientific productivity bottleneck by automating multi-stage, distributed database queries into a single application workflow. It features customized report serialization capabilities (FileExportUtil), showing strong end-to-end product awareness and developer focus.

---

👨‍💻 Author

Tahsin Ahmed GitHub: @7ahseeen

GeneLens — bringing clarity to genes, one query at a time.