view release on metacpan or  search on metacpan

html/intro.html  view on Meta::CPAN

<DD>
<code>my $gene = new CaCORE::CaBIO::Gene;</code><br/>
</DD>

<h3>Object Attributes</h3>
Each object contains a set of attributes. For example, gene has the following attributes:
<ul>
	<li>clusterId
    <li>fullName
    <li>id
    <li>symbol
</ul>

To set or retrieve the value of each attribute, there is a setter and a getter method.
<ul>
	<li>The setter method is defined as <code>set<em>Object</em></code> where <em>Object</em> is the name of the attribute, for example, <code>$gene->setSymbol</code>. When calling
		this method, the value of symbol should be passed in as a parameter. For example: <code>$gene->setSymbol("NAT2")</code> sets the $gene
		instance's symbol attribute to "NAT2";</li>
	<li>The getter method is defined as <code>get<em>Object</em></code> where <em>Object</em> is the name of the attribute, for example, <code>$gene->getSymbol</code>. When calling
		this method, the return value is the value of the attribute. For example, <code>$gene->getFullName</code> returns the full name of the $gene.</li>
</ul>

Since CaCOREperl is mainly a query application, in most cases, setter methods are used to set search criteria. Getter methods are
used to obtain the details of an object after searches.

<h3>Object Associations</h3>
Each domain object is related to certain objects. For example, gene is directly related to the following objects:
<ul>
	<li>Chromosome
    <li>DatabaseCrossReference
    <li>ExpressionFeature
    <li>GeneAlias
    <li>GeneOntology
	<li>GeneRelativeLocation
    <li>GenericReporter
    <li>Histopathology
    <li>HomologousAssociation
	<li>Library
    <li>Location
    <li>NucleicAcidSequence
    <li>OrganOntology
	<li>Pathway
    <li>Protein
    <li>Target
    <li>Taxon
</ul>

<p>The relationship between two objects can be one-to-many or many-to-one. For example, one Gene is related to multiple Pathway objects
(one-to-many), and many Genes can be related to one Taxon (many-to-one).</p>

<p>All objects that are associated with the current object can be access via the <code>getX</code> (for many-to-one associations)
	or <code>getXCollection</code> (for one-to-many associations) methods. Where "X" is the name of the associated object.
	Example: <code>$gene->getTaxon</code> retrieves the Taxon object associated with the Gene object, since one Taxon
	object is associated with many Gene objects, and <code>$gene->getPathwayCollection</code> retrieves all the Pathway objects associated,
	with the Gene object. Since one Gene object is associated with many Pathway objects.</p>

<p>The following table is a description of all objects associated with Gene, how they are related, and the methods of retrieving them.

<TABLE border="1"
          summary="This table gives some statistics about fruit
                   flies: average height and weight, and percentage
                   with red eyes (for both males and females).">
<CAPTION><EM>Gene associations</EM></CAPTION>
<TR><TH>Association Object Name<TH>Relationship<TH>Getter
	<TR><TH>Chromosome<TD>Many to one<TD>getChromosome
	<TR><TH>DatabaseCrossReference<TD>One to many<TD>getDatabaseCrossReferenceCollection
	<TR><TH>ExpressionFeature<TD>One to many<TD>getExpressionFeatureCollection
	<TR><TH>GeneAlias<TD>One to many<TD>getGeneAliasCollection
	<TR><TH>GeneOntology<TD>One to many<TD>getGeneOntologyCollection
	<TR><TH>GeneRelativeLocation<TD>One to many<TD>getGeneRelativeLocationCollection
	<TR><TH>GenericReporter<TD>One to many<TD>getGenericReporterCollection
	<TR><TH>Histopathology<TD>One to many<TD>getHistopathologyCollection
	<TR><TH>HomologousAssociation<TD>One to many<TD>getHomologousAssociationCollection
	<TR><TH>Library<TD>One to many<TD>getLibraryCollection
	<TR><TH>Location<TD>One to many<TD>getLocationCollection
	<TR><TH>NucleicAcidSequence<TD>One to many<TD>getNucleicAcidSequenceCollection
	<TR><TH>OrganOntology<TD>One to many<TD>getOrganOntologyCollection
	<TR><TH>Pathway<TD>One to many<TD>getPathwayCollection
	<TR><TH>Protein<TD>One to many<TD>getProteinCollection
	<TR><TH>Target<TD>One to many<TD>getTargetCollection
	<TR><TH>Taxon<TD>Many to one<TD>getTaxon
</TABLE>


<h3>Differences between Attributes and Associations</h3>
The following applies to all domain object packages, except for EVS objects, which is discussed in the following section.

Attributes are generally used for:
<ul>
	<li>Create search criteria. You can invoke the attribute setter methods to define the information you have in a search;
	<li>Examine the details of search result. Once the search results return (via calling ApplicationService methods or getter
	methods of associations), you can invoke the attribute getter methods to retrieve detail information of a domain object.
</ul>

Associations, on the other hand, are generally used for querying purposes. You can not call the setter methods. The getter methods
are searching methods. Under the hood, the getter methods invoke the ApplicationService search methods, which will make remote
webservice calls to the caCORE server.

<p><em>Lazy Fetch.</em> caCORE server supports (except for EVS) the so called "lazy fetch" kind of searches. This means that when you query for certain objects, only the
attributes of the objects are retrieved and returned. None of the objects associated with the target object(s) are returned.
For example, when you call $gene->getPathwayCollection, the caCORE server only retrieves and returns all the pathway objects associated with
the $gene object. It will not return any objects that are associated with the pathway objects. To retrieve those objects, you
must make subsequent calls.</p>

<h3>EVS Object Associations</h3>
EVS objects are a little different than objects of other packages.
<ul>
	<li>Search entry points are limited to DescLogicConcept and MetaThesaurusConcept. This means that when you invoke the
	ApplicationService->query and ApplicationService->queryObject methods, you can only pass in the name of these two objects
	as the target class.
	<li>Searches are "pre-fetch" instead of "lazy fetch". This means that all navigably
	associated objects, instead of directly related objects, are fetched and returned. For example, if you search for
	DescLogicConcept object, in addition to the objects that are directly related to the DescLogicConcept objects (including
	Property, HistoryRecord, EdgeProperties, TreeNode, Role, and Association), objects that are associated with these association
	objects (including Qualifier, History, and AttributeSetDescriptor), are also retrieved and returned. So when calling the
	association getter methods of these objects, CaCOREperl returns them from the local memory, instead of making a remote webservice
	call to the caCORE server.
	<li>Setter methods exist for association objects. You can call these setter methods to create search criteria.
</ul>

<h2><a name="limitations">Limitations</a></h2>