com.chemaxon.overlap.context

Class OverlapAnalysisContext<D extends Descriptor,T extends Serializable>

java.lang.Object

com.chemaxon.overlap.context.OverlapAnalysisContext<D,T>

Type Parameters:

D - Underlying descriptor type

T - Unguarded descriptor type

All Implemented Interfaces:

Guarded, Serializable

public final class OverlapAnalysisContext<D extends Descriptor,T extends Serializable>
extends Object
implements Serializable, Guarded

Context for an overlap analysis.

This context collects typical domain specific parameters required for an overlap analysis setup and execution (involving input molecule standardization, descriptor/fingerprint generation and comparison using a specific metric). Some parameters required for setup are considered to be execution environment specific, like the used ExecutorService, SubProgressObserver instances, file references, etc which are not covered by this context.

Instances of this cumulative factory class are immutable.

At least a DescriptorGenerator have to be specified; this is enforced through initial factory method initial(com.chemaxon.descriptors.common.DescriptorGenerator). Further members default to:

• standardizer: StandardizerWrappers.identityStandardizer()
• comparator: DescriptorGenerator.getDefaultComparator()
• pagesize: DEFAULT_PAGESIZE
• query pagesize: DEFAULT_QUERY_PAGESIZE
• unguarded extractor and calculator: DescriptorComparator#comparisonContext()

Since overlap analysis represents only internal identifiers and unguarded descriptor forms, associations to original structures, IDs, etc are outside the scope of this context.

IMPORTANT EFFICIENCY CONSIDERATIONS: This context holds reference to DescriptorGenerator and StandardizerWrapper instances which might ensure thread safety using ThreadLocal members. Overlap analysis and associated functionality utilize ExecutorService passed from outside. The possible pooling of worker threads by the executing environment might interfere with the thread local storage causing memory leak-like situations. To mitigate this risk following these practices are recommended:

• Never hold any OverlapAnalysisContext, DescriptorGenerator or StandardizerWrapper reference in a static context
• Periodically make any instance of the above references unreachable. It is ok to keep the reference to UnguardedPagedSimilarity instances.
• Benchmark the feasibility of deserialization before every search; keeping the memory always allocated might not provide significant performance gain.

See Also:

http://wiki.apidesign.org/wiki/APIDesignPatterns:CumulativeFactory, Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from interface com.chemaxon.descriptors.common.Guarded

Guarded.EnsureThat, Guarded.New

Field Summary

Fields

Modifier and Type	Field and Description
static int	DEFAULT_PAGESIZE Default pagesize.
static int	DEFAULT_QUERY_PAGESIZE Default number for query grouping.

Method Summary

Modifier and Type	Method and Description
<N extends Serializable> OverlapAnalysisContext<D,N>	comparisonContext(ComparisonContext<?,D,N> comparisonContext) Update represented comparison context.
PagedDescriptorStorage<D>	createEmptyStorage() Create an empty storage.
OverlapAnalysisContext<D,T>	descriptorComparator(DescriptorComparator comparator) Update descriptor comparator.
UnguardedPagedOverlap<T>	deserializeUnguardedPagedOverlap(ObjectInputStream ois, Sink<Descriptor> onDescriptorRead, SubProgressObserver po) Deserialize an UnguardedPagedSimilarity from binary serialized from.
UnguardedPagedOverlap<T>	deserializeUnguardedPagedOverlap(ObjectInputStream ois, SubProgressObserver po) Deserialize an UnguardedPagedSimilarity from binary serialized from.
DescriptorComparator<D>	getDescriptorComparator() Gets represented descriptor comparator.
DescriptorGenerator<D>	getDescriptorGenerator() Gets represented descriptor generator.
Object	getGuardObject() Gets the guard object associated to the generated descriptors/utilities.
int	getPagesize() Gets represented page size.
int	getQueryPagesize()
StandardizerWrapper	getStandardizer() Gets represented standardizer wrapper.
UnguardedDissimilarityCalculator<T>	getUnguardedDissimilarityCalculator() Gets represented unguarded dissimilarty calculator.
UnguardedExtractor<D,T>	getUnguardedExtractor() Gets represented unguarded form extractor.
static <D extends Descriptor> OverlapAnalysisContext<D,byte[]>	initial(DescriptorGenerator<D> generator) Empty representation with specified DescriptorGenerator.
static <D extends Descriptor> OverlapAnalysisContext<D,byte[]>	initial(DescriptorGenerator<D> generator, DescriptorComparator<D> comparator) Empty representation with specified DescriptorGenerator and comparator.
OverlapAnalysisContext<D,T>	pagesize(int pagesize) Update pagesize.
ImmutableList<T>	parseDescriptorsToUnguardeds(List<String> descs, SubProgressObserver po) Parse multiple descriptors and transform them into unguarded representations.
T	parseDescriptorToUnguarded(String desc) Parse descriptor and transform it into the unguarded representation.
OverlapAnalysisContext<D,T>	queryPagesize(int queryPagesize) Update query pagesize.
OverlapAnalysisContext<D,T>	standardizer(StandardizerWrapper standardizer) Update standardizer.
String	toString()
String	toString(boolean multiline) Create String representation.
T	transformMolecule(Molecule molecule) Transform molecule according to the represented context.
ImmutableList<T>	transformMolecules(List<Molecule> molecules, SubProgressObserver po) Transform molecules according to the represented context.
<N extends Serializable> OverlapAnalysisContext<D,N>	unguarded(UnguardedContext<D,N> unguardedContext) Update represented unguarded layer.
<N extends Serializable> OverlapAnalysisContext<D,N>	unguarded(UnguardedExtractor<D,N> extractor, UnguardedDissimilarityCalculator<N> unguardedCalc) Update represented unguarded layer.

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_PAGESIZE

public static final int DEFAULT_PAGESIZE

Default pagesize.

See Also:

Constant Field Values

DEFAULT_QUERY_PAGESIZE

public static final int DEFAULT_QUERY_PAGESIZE

Default number for query grouping.

See Also:

Constant Field Values

Method Detail

initial

public static <D extends Descriptor> OverlapAnalysisContext<D,byte[]> initial(DescriptorGenerator<D> generator)

Empty representation with specified DescriptorGenerator.

Note that DescriptorGenerator determines underlying Descriptor type thus it is not modifiable. Also, when calling this method the represented DescriptorComparator defaults to the comparator returned by DescriptorGenerator.getDefaultComparator().

Type Parameters:

D - Underlying descriptor type

Parameters:

generator - DescriptorGenerator represented

Returns:

Generator set; pagesize set to the DEFAULT_PAGESIZE; others initialized to defaults

initial

public static <D extends Descriptor> OverlapAnalysisContext<D,byte[]> initial(DescriptorGenerator<D> generator,
                                                                              DescriptorComparator<D> comparator)

Empty representation with specified DescriptorGenerator and comparator.

Note that DescriptorGenerator determines underlying Descriptor type thus it is not modifiable.

The specified comparator must match to the generator: the comparator needed to be created by the passed descriptor generator.

Type Parameters:

D - Underlying descriptor type

Parameters:

generator - DescriptorGenerator represented

comparator - DescriptorComparator represented

Returns:

Generator and comparator set; pagesize set to the DEFAULT_PAGESIZE; others initialized to their defaults

descriptorComparator

public OverlapAnalysisContext<D,T> descriptorComparator(DescriptorComparator comparator)

Update descriptor comparator. This method updates the underlying unguarded extractor and comparator according to the passed comparators DescriptorComparator.unguardedContext().

Note that guard objects are checked; the passed comparator must match to the underlying DescriptorGenerator specified for initial(com.chemaxon.descriptors.common.DescriptorGenerator) or initial(com.chemaxon.descriptors.common.DescriptorGenerator, com.chemaxon.descriptors.common.DescriptorComparator).

Parameters:

comparator - Comparator to be used

Returns:

New updated context instance

comparisonContext

public <N extends Serializable> OverlapAnalysisContext<D,N> comparisonContext(ComparisonContext<?,D,N> comparisonContext)

Update represented comparison context.

Note that guard objects are checked; the guard associated to the passed context Guarded.getGuardObject() must match to the represented guard getGuardObject().

Type Parameters:

N - New unguarded representation type

Parameters:

comparisonContext - New comparison context to represent

Returns:

New instance holding updated parameter

pagesize

public OverlapAnalysisContext<D,T> pagesize(int pagesize)

Update pagesize.

Parameters:

pagesize - New pagesize

Returns:

New instance holding updated parameter

queryPagesize

public OverlapAnalysisContext<D,T> queryPagesize(int queryPagesize)

Update query pagesize.

Parameters:

queryPagesize - New query pagesize

Returns:

New instance holding updated parameter

standardizer

public OverlapAnalysisContext<D,T> standardizer(StandardizerWrapper standardizer)

Update standardizer.

Parameters:

standardizer - New standardizer

Returns:

New instance holding updated parameter

unguarded

public <N extends Serializable> OverlapAnalysisContext<D,N> unguarded(UnguardedContext<D,N> unguardedContext)

Update represented unguarded layer. It is expected that the UnguardedDissimilarityCalculator represented by the given ComparisonContext be consistent with the DescriptorComparator represented by this context.

Type Parameters:

N - New unguarded representation type

Parameters:

unguardedContext - Unguarded context containing extractor/comparator

Returns:

New instance holding updated parameter

unguarded

public <N extends Serializable> OverlapAnalysisContext<D,N> unguarded(UnguardedExtractor<D,N> extractor,
                                                                      UnguardedDissimilarityCalculator<N> unguardedCalc)

Update represented unguarded layer. It is expected that the UnguardedDissimilarityCalculator passed be consistent with the DescriptorComparator represented by this context.

Type Parameters:

N - New unguarded representation type

Parameters:

extractor - Extractor of unguarded representation

unguardedCalc - Unguarded comparator

Returns:

New instance holding updated parameter

getDescriptorGenerator

public DescriptorGenerator<D> getDescriptorGenerator()

Gets represented descriptor generator.

Returns:

Represented generator

getDescriptorComparator

public DescriptorComparator<D> getDescriptorComparator()

Gets represented descriptor comparator.

Returns:

Represented comparator

getStandardizer

public StandardizerWrapper getStandardizer()

Gets represented standardizer wrapper.

Returns:

Represented standardizer

getUnguardedExtractor

public UnguardedExtractor<D,T> getUnguardedExtractor()

Gets represented unguarded form extractor.

Returns:

Represented extractot function

getPagesize

public int getPagesize()

Gets represented page size.

Returns:

Represented page size

getQueryPagesize

public int getQueryPagesize()

getUnguardedDissimilarityCalculator

public UnguardedDissimilarityCalculator<T> getUnguardedDissimilarityCalculator()

Gets represented unguarded dissimilarty calculator.

Returns:

Represented ungarded dissimilarity calculator

createEmptyStorage

public PagedDescriptorStorage<D> createEmptyStorage()

Create an empty storage.

Note that the returned storage has no reference to the serializer of this context.

Returns:

Empty storage

deserializeUnguardedPagedOverlap

public UnguardedPagedOverlap<T> deserializeUnguardedPagedOverlap(ObjectInputStream ois,
                                                                 SubProgressObserver po)
                                                          throws IOException,
                                                                 ClassNotFoundException

Deserialize an UnguardedPagedSimilarity from binary serialized from.

This method delegates call to PagedDescriptorStorage#deserializeUnguarded(int, com.chemaxon.descriptors.common.DescriptorGenerator, com.google.common.base.Function, com.chemaxon.overlap.unguarded.UnguardedDissimilarityCalculator, java.io.ObjectInputStream, com.chemaxon.calculations.common.SubProgressObserver) passing represented context information.

Parameters:

ois - Source stream to deserialize from

po - Progress observer to track progress. Method ProgressObserver.done() will be invoked upon completion

Returns:

Deserialized searcher

Throws:

IOException - Propagated from deserialization

ClassNotFoundException - Propagated from deserialization

deserializeUnguardedPagedOverlap

public UnguardedPagedOverlap<T> deserializeUnguardedPagedOverlap(ObjectInputStream ois,
                                                                 Sink<Descriptor> onDescriptorRead,
                                                                 SubProgressObserver po)
                                                          throws IOException,
                                                                 ClassNotFoundException

Deserialize an UnguardedPagedSimilarity from binary serialized from.

This method delegates call to PagedDescriptorStorage#deserializeUnguarded(int, com.chemaxon.descriptors.common.DescriptorGenerator, com.google.common.base.Function, com.chemaxon.overlap.unguarded.UnguardedDissimilarityCalculator, java.io.ObjectInputStream, com.chemaxon.calculations.common.SubProgressObserver) passing represented context information.

Parameters:

ois - Source stream to deserialize from

onDescriptorRead - Callback to invoke on each deserialized descriptor or null

po - Progress observer to track progress. Method ProgressObserver.done() will be invoked upon completion

Returns:

Deserialized searcher

Throws:

IOException - Propagated from deserialization

ClassNotFoundException - Propagated from deserialization

parseDescriptorToUnguarded

public T parseDescriptorToUnguarded(String desc)

Parse descriptor and transform it into the unguarded representation.

Parameters:

desc - Descriptor String representation

Returns:

Unguarded representation of the parsed descriptor

parseDescriptorsToUnguardeds

public ImmutableList<T> parseDescriptorsToUnguardeds(List<String> descs,
                                                     SubProgressObserver po)

Parse multiple descriptors and transform them into unguarded representations.

Parameters:

descs - Descriptors String representations

po - Progress observer to track progress

Returns:

List of unguarded descriptors suitable to pass to searchers

transformMolecule

public T transformMolecule(Molecule molecule)

Transform molecule according to the represented context.

The following steps are executed:

• Cloning the molecule for further steps using Molecule.cloneMolecule()
• Standardize with the represented StandardizerWrapper using StandardizerWrapper.standardize(chemaxon.struc.Molecule)
• Generate descriptor with the represented DescriptorGenerator using DescriptorGenerator.generateDescriptor(chemaxon.struc.Molecule)
• Retrieve unguarded descriptor contents with the represented retriever Function

Parameters:

molecule - Molecule to transform. The molecule is cloned using Molecule.cloneMolecule() before transformations.

Returns:

Unguarded form

transformMolecules

public ImmutableList<T> transformMolecules(List<Molecule> molecules,
                                           SubProgressObserver po)

Transform molecules according to the represented context.

For each molecule the following steps are executed:

• Cloning the molecule for further steps using Molecule.cloneMolecule()
• Standardize with the represented StandardizerWrapper using StandardizerWrapper.standardize(chemaxon.struc.Molecule)
• Generate descriptor with the represented DescriptorGenerator using DescriptorGenerator.generateDescriptor(chemaxon.struc.Molecule)
• Retrieve unguarded descriptor contents with the represented retriever Function

Parameters:

molecules - Molecules to transform. The molecules are cloned using Molecule.cloneMolecule() before transformations.

po - Progress observer to track progress

Returns:

List of unguarded descriptors suitable to pass to searchers.

toString

public String toString(boolean multiline)

Create String representation.

Parameters:

multiline - Create multiline (more readable) output.

Returns:

String representation

toString

public String toString()

Overrides:

toString in class Object

getGuardObject

public Object getGuardObject()

Description copied from interface: Guarded

Gets the guard object associated to the generated descriptors/utilities. Note that serialization/deserialization must preserve guard object reference.

This method is intended to use only for ensuring the compatibility of manipulated objects.

Implementations might use the associated DescriptorGenerator or DescriptorParameters reference as the guard object, however it is a non recommended practice to use this method to access the associated generator to perform further operations on it.

Specified by:

getGuardObject in interface Guarded

Returns:

The guard object, can not be null.