org.ujoframework.Ujo Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of ujo-orm Show documentation
Quick ORM implementation based on the UJO objects.
There is a newer version: 1.22
/*
 *  Copyright 2007 Paul Ponec
 *
 *  Licensed under the Apache License, Version 2.0 (the "License");
 *  you may not use this file except in compliance with the License.
 *  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 *  Unless required by applicable law or agreed to in writing, software
 *  distributed under the License is distributed on an "AS IS" BASIS,
 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *  See the License for the specific language governing permissions and
 *  limitations under the License.
 */

package org.ujoframework;

import org.ujoframework.UjoPropertyList;
import org.ujoframework.extensions.UjoAction;

/**
 *  
 * UJO means a Unified Java Object and its implementations provides a similar service like a JavaBeans class.
 * Ujo is a basic inteface of the UJO Framework together with an interface UjoProperty .
 * Basic two methods are writeProperty(..) and readProperty(..) for a manipulation with a value;
 * next method readAuthorization(..) recommends an authorizaton for a required action, selected Property and context;
 * the last method returns all properties of current UJO object.
 * See a general prologue for more information or see some implementations.
 *
 *The fastest way to use the interface is to extend an abstract parrent:
 *import org.ujoframework.implementation.map.*;
 *public class Person extends MapUjo {
 *    
 *  public static final UjoProperty<Person, String > NAME = newProperty("Name", String.class);
 *  public static final UjoProperty<Person, Boolean> MALE = newProperty("Male", Boolean.class);
 *  public static final UjoProperty<Person, Double > CASH = newProperty("Cash", 0d);
 *    
 *  public void addCash(double cash) {
 *    double newCash = CASH.of(this) + cash;
 *    CASH.setValue(this, newCash);
 *  }
 *}
 * 
 * @author Pavel Ponec
 * @see UjoProperty
 * @composed 1 - 1 UjoPropertyList
 */
public interface Ujo {
    
    
    /** It is a common method for reading all object values, however there is strongly recomended to use a method 
     * UjoProperty.getValue(Ujo)
     * to an external access for a better type safe.
     * The method have got a strategy place for an implementation of several listeners and convertors. 
     * 
NOTE 1: A null value is always replaced by a default property value.
     * 
NOTE 2: A reaction on an incorrect property depends on the implementation.
     *
     * @param property Property must be a direct type only!
     * @return Property value
     * @see UjoProperty#getValue(Ujo)
     * @see UjoProperty#isDirect()
     */
    public Object readValue(UjoProperty property);
    
    
    /** It is a common method for writing all object values, however there is strongly recomended to use a method 
     * UjoProperty.setValue(Ujo,Object) 
     * to an external access for a better type safe.
     * The method have got a strategy place for an implementation of several listeners and validators. 
     * 
NOTE: A reaction on an incorrect property depends on the implementation.
     *
     * @param property Property must be a direct type only!
     * @see UjoProperty#setValue(Ujo,Object)
     * @see UjoProperty#isDirect()
     */
    public void writeValue(UjoProperty property, Object value);
    
    /** Returns all direct properties.
     * There is recommended to be a "name" of each property is unique (but it is NOT a necessary condition).
     * Two attributes with the same "name" must be demarked by a different ACTION_XML_ELEMENT authorization for a XML export.
     *
     * 
An index property in the array UJO must be unique a continuous, an order of property array depends on an implementation of UJO object.
     * @see UjoProperty#isDirect()
     */
    public UjoPropertyList readProperties();
    
    /**
     * Get an authorization of the property for different actions.
     * 
There is recommended to return a true value for all actions by a default.
     * 
Note: An implemetace may return the original property array so it is possible to change some original property in the array from an extefnal code.
     *
     * @param action Type of request. See constant(s) UjoAction.ACTION_* for more information. 
     *        The action must not be null, however there is allowed to use a dummy constant UjoAction.DUMMY.
     * @param property A property of the Ujo
     * @param value A property value
     * @return Returns a TRUE value in case the property is authorized successfully.
     * @see org.ujoframework.extensions.UjoAction
     */
    public boolean readAuthorization(UjoAction action, UjoProperty property, Object value);
    
}