001: // THIS SOFTWARE IS PROVIDED BY SOFTARIS PTY.LTD. AND OTHER METABOSS
002: // CONTRIBUTORS ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING,
003: // BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
004: // FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL SOFTARIS PTY.LTD.
005: // OR OTHER METABOSS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
006: // INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
007: // LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA,
008: // OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
009: // LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
010: // NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
011: // EVEN IF SOFTARIS PTY.LTD. OR OTHER METABOSS CONTRIBUTORS ARE ADVISED OF THE
012: // POSSIBILITY OF SUCH DAMAGE.
013: //
014: // Copyright 2000-2005 © Softaris Pty.Ltd. All Rights Reserved.
015: package com.metaboss.sdlctools.domains.enterprisemodel;
016:
017: import com.metaboss.enterprise.bo.BOException;
018: import com.metaboss.sdlctools.types.enterprisemodel.SelectorCardinality;
019: import com.oldboss.framework.bo.BOObject;
020:
021: /**
022: * Selector is the definition of the sub-query available on the
023: * entity collection. Such sub-query allows to further narrow collection
024: * of entities obtained via association navigation. Selector is different to association.
025: * Each association results in 'Foreign Key' type of relationship between entities.
026: * Selector results in just an extra method on the entity collection and has
027: * no impact on the database structure. Lets look at the example :
028: * <UL>
029: * <LI>Client entity is associated with Order entity via ClientPlacesOrder
030: * association. This means that the Client will have the method :
031: * <br><pre><code>
032: * // Returns all orders owned by the client regardless of their current state
033: * public BOOrderCollection getOrders()
034: * </code></pre><br>
035: * By calling this method program can obtain the collection of all orders ever given by the client</LI>
036: * <LI>At the same time Order entity has following selectors defined : MostRecentOrder (returning zero or one Order),
037: * ActiveOrders (returning zero or more Orders) and CancelledOrders (again returning zero or more Orders).
038: * In this case Order Collection will have following methods :
039: * <br><pre><code>
040: * // Returns last placed order ot null if this collection is empty
041: * public BOOrder selectMostRecentOrder()
042: * // Returns collection of zero or more active orders
043: * public BOOrderCollection selectActiveOrders()
044: * // Returns collection of zero or more cancelled orders
045: * public BOOrderCollection selectCancelledOrders()
046: * </code></pre><br> By calling this methods program can select single
047: * entity or sub-collection of entities satisfying particular criteria.</LI>
048: * <LI>Using both facilities above, calling program can, for example, obtain
049: * desired orders for the client in one stroke as follows :
050: * <br><pre><code>
051: * BOOrderCollection lActiveOrders = null;
052: * BOOrderCollection lLastCancelledOrder = null;
053: * // Get client's active orders
054: * lActiveOrders = lClient.getOrders().selectActiveOrders();
055: * // Now get most recent cancelled order
056: * lLastCancelledOrder = lClient.getOrders().selectCancelledOrders().selectMostRecentOrder();
057: * </code></pre><br></LI>
058: * <LI>This feature is even more powerful when combined with collection association methods.
059: * To further above example, suppose Order entity is associated with Product
060: * (many Orders can refer to one Product). In this case to get all products client is waiting on :
061: * <br><pre><code>
062: * BOProductCollection lDesiredProducts = null;
063: * // Get all distinct products from client's active orders
064: * lDesiredProducts = lClient.getOrders().selectActiveOrders().getDistinctProducts();
065: * </code></pre><br></LI>
066: * </UL>
067: * Note that underlying implementation of collections and selectors ensures that the
068: * actual selection and loading is deferred to database, all subqueries are combined in one
069: * and actual query only executed when actual data is about to be used.
070: * This ensures maximum possible speed without compromising reuse.
071: * Selector Name must be unique within particular entity. Selector definition contains
072: * list of input parameters. Any number of parameters of any valid datatype can be specified.
073: * Selector definition specifies selector cardinality. This controls the patterns of how selector method is named
074: * (i.e. whether to use singular or plural name).
075: * <BR>
076: * At the storage interface level, the details of any number of selectors are
077: * carried in the array of com.metaboss.enterprise.ps.STSelectorDetails[] structures
078: * it contains 'history' of all selectors and associations invoked. Array of these structures
079: * is passed to majority of all get methods.
080: */
081: public interface BOSelector extends BOObject {
082: /** Retrieves unique reference */
083: public String getRef() throws BOException;
084:
085: /** Returns entity, which owns this selector. Together with the selector name
086: * forms the unique selector identifier */
087: public BOEntity getEntity() throws BOException;
088:
089: /** Retrieves selector name. Consists of the prefix and suffix
090: * This name is always present */
091: public String getName() throws BOException;
092:
093: /** Retrieves description */
094: public String getDescription() throws BOException;
095:
096: /** Sets description */
097: public void setDescription(String pDescription) throws BOException;
098:
099: /** Returns boolean flag indicating if this selector is an implicit selector */
100: public boolean isImplicit() throws BOException;
101:
102: /** Sets boolean flag indicating if this selector is an implicit selector */
103: public void setIsImplicit(boolean isImplicit) throws BOException;
104:
105: /** Retrieves cardinality for the return from this selector. */
106: public SelectorCardinality getCardinality() throws BOException;
107:
108: /** Sets cardinality for the return from this selector. */
109: public void setCardinality(SelectorCardinality pCardinality)
110: throws BOException;
111:
112: /** Retireves the list of input fields */
113: public BOSelectorInputFieldList getInputFields() throws BOException;
114:
115: /** Retrieves text of java implementation template of the selector */
116: public String getJavaSelector() throws BOException;
117:
118: /** Sets text of java implementation template of the selector */
119: public void setJavaSelector(String pJavaSelector)
120: throws BOException;
121:
122: /** Retrieves text of SQL implementation template of the selector */
123: public String getSQLSelector() throws BOException;
124:
125: /** Sets text of SQL implementation template of the selector */
126: public void setSQLSelector(String pSQLSelector) throws BOException;
127: }
|