Class GeneWebService

java.lang.Object

ubic.gemma.rest.GeneWebService

@Service
@Path("/genes")
public class GeneWebService
extends Object

RESTful interface for genes. Does not have an 'all' endpoint (no use-cases). Most methods also have a taxon-specific counterpart in the TaxaWebService (useful when using the 'official symbol' identifier, as this class will just return a random taxon homologue).

Author:

tesarst

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	GeneWebService.CompositeSequenceSummaryValueObject	Enriched per-probe row returned by getGeneProbes(GeneArg, OffsetArg, LimitArg, CursorArg, boolean) when summary=true.
static class	GeneWebService.CursorPaginatedResponseDataObjectCompositeSequenceSummaryValueObject	Cursor-mode response shape for getGeneProbes(GeneArg, OffsetArg, LimitArg, CursorArg, boolean) when summary=true.
static class	GeneWebService.GeneDifferentialExpressionGroupValueObject	One experiment's DEA results for the requested gene.
static class	GeneWebService.PaginatedResponseDataObjectCompositeSequenceSummaryValueObject	Legacy-mode response shape for getGeneProbes(GeneArg, OffsetArg, LimitArg, CursorArg, boolean) when summary=true.

Constructor Summary

Constructors

Constructor	Description
GeneWebService()

Method Summary

Modifier and Type	Method	Description
ResponseDataObject<List<GeneWebService.GeneDifferentialExpressionGroupValueObject>>	getGeneDifferentialExpression(GeneArg<?> geneArg, double threshold, int limit)	Retrieves the differential expression results for the given gene across all experiments the caller has access to (ACL-filtered downstream).
ResponseDataObject<List<GeneOntologyTermValueObject>>	getGeneGoTerms(GeneArg<?> geneArg)	Retrieves the GO terms of the given gene.
ResponseDataObject<Collection<GeneValueObject>>	getGeneHomologues(GeneArg<?> geneArg)	Retrieves the homologues of the given gene.
ResponseDataObject<List<PhysicalLocationValueObject>>	getGeneLocations(GeneArg<?> geneArg)	Retrieves the physical location of the given gene.
ResponseDataObject<GeneValueObject>	getGeneOverview(GeneArg<?> geneArg)	Retrieves a fully-populated overview of the given gene, suitable for rendering the gene-page header in gemma-curation-ui.
Object	getGeneProbes(GeneArg<?> geneArg, OffsetArg offset, LimitArg limit, CursorArg cursorArg, boolean summary)	Retrieves the probes (composite sequences) with this gene.
Object	getGenes(OffsetArg offsetArg, LimitArg limitArg, CursorArg cursorArg)
ResponseDataObject<List<GeneValueObject>>	getGenesByIds(GeneArrayArg genes)
jakarta.ws.rs.core.Response	refreshGenesProbes()	Refresh gene-to-probe associations.
ResponseDataObject<List<GeneValueObject>>	searchGenes(String query, TaxonArg<?> taxonArg, int limit)	Free-text typeahead for genes.

Methods inherited from class Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

GeneWebService

public GeneWebService()

Method Details

getGenes

@GET
@Produces("application/json")
public Object getGenes(@QueryParam("offset") @DefaultValue("0")
 OffsetArg offsetArg,
 @QueryParam("limit") @DefaultValue("20")
 LimitArg limitArg,
 @QueryParam("cursor")
 CursorArg cursorArg)

searchGenes

@GET
@Path("/search")
@Produces("application/json")
public ResponseDataObject<List<GeneValueObject>> searchGenes(@QueryParam("query")
 String query,
 @QueryParam("taxon")
 TaxonArg<?> taxonArg,
 @QueryParam("limit") @DefaultValue("20")
 int limit)

Free-text typeahead for genes. Shim over SearchService so the curation-UI can keep calling GET /genes/search?query=... instead of the canonical GET /search?query=...&resultTypes=...Gene.

Path is declared before getGenesByIds(GeneArrayArg) (which owns GET /genes/{genes}) so JAX-RS resolves the literal "search" segment before falling through to the template variable.

Parameters:

query - non-empty free-text query (symbol, alias, NCBI id, …).

taxonArg - optional — when supplied, results are scoped to that taxon.

limit - 1..50; default 20.

getGenesByIds

@GET
@Path("/{genes}")
@Produces("application/json")
public ResponseDataObject<List<GeneValueObject>> getGenesByIds(@PathParam("genes")
 GeneArrayArg genes)

getGeneLocations

@GET
@Path("/{gene}/locations")
@Produces("application/json")
public ResponseDataObject<List<PhysicalLocationValueObject>> getGeneLocations(@PathParam("gene")
 GeneArg<?> geneArg)

Retrieves the physical location of the given gene.

Parameters:

geneArg - can either be the NCBI ID, Ensembl ID or official symbol. NCBI ID is most efficient (and guaranteed to be unique). Official symbol returns a gene homologue on a random taxon.

getGeneProbes

@GET
@Path("/{gene}/probes")
@Produces("application/json")
public Object getGeneProbes(@PathParam("gene")
 GeneArg<?> geneArg,
 @QueryParam("offset") @DefaultValue("0")
 OffsetArg offset,
 @QueryParam("limit") @DefaultValue("20")
 LimitArg limit,
 @QueryParam("cursor")
 CursorArg cursorArg,
 @QueryParam("summary") @DefaultValue("false")
 boolean summary)

Retrieves the probes (composite sequences) with this gene.

Parameters:

geneArg - can either be the NCBI ID, Ensembl ID or official symbol. NCBI ID is most efficient (and guaranteed to be unique). Official symbol returns a gene homologue on a random taxon.

refreshGenesProbes

@GET
@Path("/probes/refresh")
@PreAuthorize("hasAuthority('GROUP_CURATOR')")
public jakarta.ws.rs.core.Response refreshGenesProbes()

Refresh gene-to-probe associations.

getGeneGoTerms

@GET
@Path("/{gene}/goTerms")
@Produces("application/json")
public ResponseDataObject<List<GeneOntologyTermValueObject>> getGeneGoTerms(@PathParam("gene")
 GeneArg<?> geneArg)

Retrieves the GO terms of the given gene.

Parameters:

geneArg - can either be the NCBI ID, Ensembl ID or official symbol. NCBI ID is most efficient (and guaranteed to be unique). Official symbol returns a gene homologue on a random taxon.

getGeneOverview

@GET
@Path("/{gene}/overview")
@Produces("application/json")
public ResponseDataObject<GeneValueObject> getGeneOverview(@PathParam("gene")
 GeneArg<?> geneArg)

Retrieves a fully-populated overview of the given gene, suitable for rendering the gene-page header in gemma-curation-ui. Replaces the legacy GeneController.loadGeneDetails(Long) DWR call.

The returned VO carries: aliases, multifunctionality rank, composite-sequence count, platform count, gene-set memberships, homologues, GO-term count, and the associated-experiment count (filled in by populateAssociatedExperimentCount).

Parameters:

geneArg - can either be the NCBI ID, Ensembl ID or official symbol. NCBI ID is most efficient (and guaranteed to be unique). Official symbol returns a gene homologue on a random taxon.

getGeneHomologues

@GET
@Path("/{gene}/homologues")
@Produces("application/json")
public ResponseDataObject<Collection<GeneValueObject>> getGeneHomologues(@PathParam("gene")
 GeneArg<?> geneArg)

Retrieves the homologues of the given gene. Single-purpose subset of getGeneOverview(GeneArg) for callers that only need the homologue list.

Parameters:

geneArg - can either be the NCBI ID, Ensembl ID or official symbol. NCBI ID is most efficient (and guaranteed to be unique). Official symbol returns a gene homologue on a random taxon.

getGeneDifferentialExpression

@GET
@Path("/{gene}/differentialExpression")
@Produces("application/json")
public ResponseDataObject<List<GeneWebService.GeneDifferentialExpressionGroupValueObject>> getGeneDifferentialExpression(@PathParam("gene")
 GeneArg<?> geneArg,
 @QueryParam("threshold") @DefaultValue("1.0")
 double threshold,
 @QueryParam("limit") @DefaultValue("-1")
 int limit)

Retrieves the differential expression results for the given gene across all experiments the caller has access to (ACL-filtered downstream).

Wraps DifferentialExpressionResultService.findByGene(Gene, boolean, boolean, double, int) with useGene2Cs=true and keepNonSpecificProbes=false — matches the convention used by the dataset-scoped DEA endpoint in DatasetsWebService.

The cold-cache latency on this path (~4s for high-traffic genes like TP53) is mitigated by DiffExGeneWarmupService which periodically re-runs the underlying call for a seed gene list. See PERF_PROBE_REPORT_ROUND3.md §C1.

Parameters:

geneArg - can either be the NCBI ID, Ensembl ID or official symbol. NCBI ID is most efficient (and guaranteed to be unique). Official symbol returns a gene homologue on a random taxon.

threshold - optional q/p-value threshold. Defaults to 1.0 (no filtering).

limit - optional cap on results returned per experiment grouping. -1 means no cap.