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.enterprise.datatypes;
016:
017: /** Definition of the generic Data Type interface. This interface is a base interface,
018: * which must be implemented by all datatypes in enterprise.
019: * <P> Every datatype must support two special states 'Empty' and 'Concealed'.
020: * Empty instance is a typesafe way to pass around null values. Concealed
021: * instance is a typesafe way to pass around data, which user in fact is not allowed to see.
022: * Support for these states is realised by having following methods on every datatype class:
023: * <UL>
024: * <LI>public boolean isEmpty(). Returns true if this instance of datatype is empty.</LI>
025: * <LI>public static <Data Type> createEmpty(). Creates empty instance of the datatype.</LI>
026: * <LI>public boolean isConcealed(). Returns true if this instance of datatype is concealed.</LI>
027: * <LI>public static <Data Type> createConcealed(). Creates concealed instance of the datatype.</LI>
028: * </UL>
029: * Note that concealed instance of datatype does not have any data inside, so even with debugger
030: * it is impossible to see the content. This is achieved by having static creator of the concealed instance, which
031: * makes it impossible for datatype implementor to forget to wipe out the content (alternative might have been
032: * providing conceal() instance method, but this would rely on implementation to do the right thing and
033: * wipe the data content out)</P>
034: * <P> Every datatype can support unlimited number of application level methods (They are the reason
035: * we have a datatype in a first place !). The methods generally fall into one of four categories :
036: * <UL>
037: * <LI>
038: * Creators - methods used to create an instance of the datatype from raw data of some type.
039: * Normally they are public static methods taking the raw data argument and returning an instance of the datatype.
040: * Creators should always validate data and throw DataTypeValidationException in case of error.
041: * One creator is mandatory : public static <Data Type> createFromString(String pString).
042: * This creator is expected to create an instance from the person readable string representation.
043: * </LI>
044: * <LI>
045: * Validators - methods used to validate proposed raw data of some type before creation can occur.
046: * It is a good idea to have matching validator for each creator (and internally just call validator at the
047: * beginning of the creator method) One validator is mandatory :
048: * public static void validateString(String pString). This validator is expected to validate person readable string representation.
049: * </LI>
050: * <LI>
051: * Getters - methods used to retrieve raw data of some type from instance. Notmally they are
052: * instance methods taking no arguments and returning raw data type. It is a good idea to have matching
053: * getter for each creator. One getter is mandatory : public String toString(). This getter
054: * is expected to return person readable string representation.
055: * </LI>
056: * <LI>
057: * Other - other method which retrive some values in some convenient form or perform
058: * some data transformations (i.e Rectangle class may have public double getArea() method or
059: * public void move(int x, int y) method ). These methods must be implemented in a way that they are able to deal with
060: * empty and concealed states of the datatype - the least they should do is to throw appropriate exception.
061: * </LI>
062: * </UL>
063: * See <A HREF="DataTypeInvalidOperationForConcealedInstanceException.html">DataTypeInvalidOperationForConcealedInstanceException</A> exception or
064: * <A HREF="DataTypeInvalidOperationForEmptyInstanceException.html">DataTypeInvalidOperationForEmptyInstanceException</A> exception
065: * for discussion on the best approach</P>
066: * <P> Every datatype must implement either Serializable or Externalizable interface
067: * (the reason this interface does not extend them, because we do not know which one !).
068: * The Serialization/Externalization is the most native way for java to persist and transmit value objects
069: * so this requirement is only natural.</P>
070: * <P> In addition to serialization, every datatype must support other translation features such as
071: * translations to/from java primitive type, to/from jdbc (java.sql.*) type and xml (org.w3c.dom.*) types.
072: * This is achieved by each DataType providing access to DataTypeTranslationMetadata class, which in turn
073: * has all details for applications to perform translation. This is realised by each DataType
074: * having public static DataTypeTranslationMetadata getTranslationMetadata() method to support translation
075: * features. See <A HREF="DataTypeTranslationMetadata.html">DataTypeTranslationMetadata</A> class for details.</P>
076: *
077: */
078: public interface DataType {
079: /** Returns true if this instance is empty.
080: * In MetaBoss enterprise model if the reference to the datatype instance
081: * is null - it means that the instance has not been retrieved from storage or
082: * instance has not been specified by user. For the read functionality it
083: * means that reading of the field must be attempted, for the update functionality
084: * it means that the value of the field should be left intact during the update.
085: * If on the other hand if the reference to the datatype instance is not null, but
086: * contains empty instance (isEmpty() method returns true) it should be treated as
087: * meaningfull value (NULL value at the database). For the read functionality it
088: * means that reading of the field has already been done and the field is empty
089: * , for the update functionality it means that the value of the field should be set to empty
090: * during the update.
091: */
092: public boolean isEmpty();
093:
094: /** Returns true if this instance is concealed.
095: * In MetaBoss enterprise model if the user asking for data and he/she is not authorised
096: * to see certain fields (column level security) - he/she will still get the same structures returned
097: * from the same services but some fields will be concealed. This means that the field
098: * will not physically contain any value (concealed field can not be cracked or unscrambled
099: * because there is nothing in it !). User interface should check for it and
100: * display the data accordingly (i.e '*********" or 'xxxxxxxxxx' or just empty.
101: * If update functionality gets concealed field back from client it should
102: * just ignore it (as if user is not planning to change this field).
103: */
104: public boolean isConcealed();
105:
106: /**The java.lang.Object's public String toString() method must be implemented in each datatype.
107: * In words of java.lang.Object's javadoc <I>"toString() returns a string representation of the object.
108: * In general, the toString method returns a string that "textually represents" this object.
109: * The result should be a concise but informative representation that is easy for a person to read.
110: * It is recommended that all subclasses override this method."
111: * Note that this method should deal with empty and concealed values and not throw
112: * exceptions. This is necessary to enable presentation of data. Empty should
113: * result in empty string. Concealed may result in something like "########" or "********" etc. */
114: public String toString();
115: }
|