source: trunk/doc/src/docbook/examples/AnyItem.java.txt @ 5675

/*
  $Id $

  Copyright (C) 2011 Your name

  This file is part of BASE - BioArray Software Environment.
  Available at http://base.thep.lu.se/

  BASE is free software; you can redistribute it and/or
  modify it under the terms of the GNU General Public License
  as published by the Free Software Foundation; either version 3
  of the License, or (at your option) any later version.

  BASE is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  GNU General Public License for more details.

  You should have received a copy of the GNU General Public License
  along with BASE. If not, see <http://www.gnu.org/licenses/>.
*/
package net.sf.basedb.core;
import net.sf.basedb.core.data.AnyData;
/**
  This class is used to represent an AnyItem in BASE.

  @author Your name
  @since 3.0
  @see AnyData
  @base.modified $Date: 2011-06-28 13:19:45 +0000 (Tue, 28 Jun 2011) $
*/
public class AnyItem
  extends CommonItem<AnyData>
  implements Subtypable
{

  /**
    Create a new <code>AnyItem</code> item.
  
    @param dc The <code>DbControl</code> which will be used for
      permission checking and database access
    @return The new <code>AnyItem</code> item
    @throws BaseException If there is an error
  */
  public static AnyItem getNew(DbControl dc)
    throws BaseException
  {
    AnyItem a = dc.newItem(AnyItem.class);
    a.setName("New any item");
    return a;
  }

  /**
    Get an <code>AnyItem</code> item when you know the id.
  
    @param dc The <code>DbControl</code> which will be used for
      permission checking and database access.
    @param id The id of the item to load
    @return The <code>AnyItem</code> item
    @throws ItemNotFoundException If an item with the specified 
      id is not found
    @throws PermissionDeniedException If the logged in user doesn't 
      have read permission to the item
    @throws BaseException If there is another error
  */
  public static AnyItem getById(DbControl dc, int id)
    throws ItemNotFoundException, PermissionDeniedException, BaseException
  {
    AnyItem a = dc.loadItem(AnyItem.class, id);
    if (a == null) throw new ItemNotFoundException("AnyItem[id="+id+"]");
    return a;
  }

  /**
    Get a query configured to retrieve anyitems. 
    @return An {@link ItemQuery} object
  */
  public static ItemQuery<AnyItem> getQuery()
  {
    return new ItemQuery<AnyItem>(AnyItem.class);
  }

  // Constructor
  AnyItem(AnyData anyData)
  {
    super(anyData);
  }

  /*
    From the BasicItem class
    -------------------------------------------
  */
  /**
    TODO - Check if:
    <ul>
    <li>other items are using this AnyItem
    </ul>
    (or remove this method)
  */
  public boolean isUsed()
    throws BaseException
  {
    org.hibernate.Session session = getDbControl().getHibernateSession();
    org.hibernate.Query query = 
      HibernateUtil.getPredefinedQuery(session, "GET_OTHER_ITEM_FOR_ANYITEM", "count(*)");
    /*
      SELECT {1}
      FROM OtherItemData o
      WHERE o.anyItem = :anyItem
    */
    query.setEntity("anyItem", this.getData());
    boolean used = HibernateUtil.loadData(Long.class, query) > 0;
    return used || super.isUsed();
  }
  
  /**
    TODO - Get all:
    <ul>
    <li>other items using this AnyItem
    <ul>
    (or remove this method)
  */
  @Override
  public Set<ItemProxy> getUsingItems()
  {
    Set<ItemProxy> using = super.getUsingItems();
    org.hibernate.Session session = getDbControl().getHibernateSession();
      
    // Other items
    org.hibernate.Query query = HibernateUtil.getPredefinedQuery(session, 
        "GET_OTHER_ITEM_FOR_ANYITEM", "o.id");
    /*
      SELECT {1}
      FROM OtherItemData o
      WHERE o.anyItem = :anyItem
    */
    query.setEntity("anyItem", this.getData());
    addUsingItems(using, Item.OTHER, query);
    return using;
  }
  
  /**
    TODO - grant or deny extra permissions or remove this method
  */
  void initPermissions(int granted, int denied)
    throws BaseException
  {
    // Place your extra permissions here
    super.initPermissions(granted, denied);
  }
  /**
    TODO - set default items
    (or remove this method
  */
  void setProjectDefaults(Project activeProject)
    throws BaseException
  {
    // The protocol used to create the item
    if (!protocolHasBeenSet)
    {
      ProtocolData protocol = 
        (ProtocolData)activeProject.findDefaultRelatedData(dc, this, Item.PROTOCOL, false);
      if (protocol != null) 
      {
        getData().setProtocol(protocol);
        protocolHasBeenSet = true;
      }
    }
  }
  // -------------------------------------------
  /*
    From the Subtypable interface
    -----------------------------
  */
  @Override
  @SubtypableRelatedItems({Item.PROTOCOL})
  public ItemSubtype getItemSubtype()
  {
    return getDbControl().getItem(ItemSubtype.class, getData().getItemSubtype());
  }
  @Override
  public void setItemSubtype(ItemSubtype subtype)
  {
    checkPermission(Permission.WRITE);
    if (subtype != null)
    {
      subtype.setOnItem(this);
    }
    else
    {
      getData().setItemSubtype(null);
    }
  }
  // -------------------------------------------

  // TODO - Methods below this line are examples only, modify or remove as needed
  /**
    Get the value of the string property.
  */
  public String getStringProperty()
  {
    return getData().getStringProperty();
  }
  public static final int MAX_STRINGPROPERTY_LENGTH = AnyData.MAX_STRINGPROPERTY_LENGTH;
  /**
    Set the value of the string property. Null values are not 
    allowed and the length must be shorter than 
    {@link #MAX_STRINGPROPERTY_LENGTH}.
    @param value The new value
    @throws PermissionDeniedException If the logged in user
      doesn't have write permission
    @throws InvalidDataException If the value is null or too long
  */
  public void setStringProperty(String value)
    throws PermissionDeniedException, InvalidDataException
  {
    checkPermission(Permission.WRITE);
    getData.setStringProperty(
      StringUtil.setNotNullString(value, "stringProperty", MAX_STRINGPROPERTY_LENGTH)
    );
  }

  /**
    Get the value of the int property.
  */
  public int getIntProperty()
  {
    return getData().getIntProperty();
  }
  /**
    Set the value of the int property. The value mustn't be less than
    zero.
    @param value The new value
    @throws PermissionDeniedException If the logged in user
      doesn't have write permission
    @throws InvalidDataException If the value is less than zero
  */
  public void setIntProperty(int value)
    throws PermissionDeniedException, InvalidDataException
  {
    checkPermission(Permission.WRITE);
    getData.setIntProperty(
      IntegerUtil.checkMin(value, "intProperty", 0)
    );
  }

  /**
    Get the value of the boolean property.
  */
  public boolean isBooleanProperty()
  {
    return getData().isBooleanProperty();
  }
  /**
    Set the value of the boolean property. 
    @param value The new value
    @throws PermissionDeniedException If the logged in user
      doesn't have write permission
  */
  public void setBooleanProperty(boolean value)
    throws PermissionDeniedException
  {
    checkPermission(Permission.WRITE);
    getData.setBooleanProperty(value);
  }

  /**
    Get the value of the date property.
    @return A date object or null if unknown
  */
  public Date getDateProperty()
  {
    return DateUtil.copy(getData().getDateProperty());
  }
  /**
    Set the value of the date property. Null values are allowed.
    @param value The new value
    @throws PermissionDeniedException If the logged in user
      doesn't have write permission
  */
  public void setDateProperty(Date value)
    throws PermissionDeniedException
  {
    checkPermission(Permission.WRITE);
    getData().setDateProperty(DateUtil.setNullableDate(value, "dateProperty"));
  }
  
  /**
    Get the associated other item.
    @return The <code>OtherItem</code> item
    @throws PermissionDeniedException If the logged in user 
      doesn't have read permission
    @throws BaseException If there is another error
  */
  public OtherItem getOtherItem()
    throws PermissionDeniedException, BaseException
  {
    return getDbControl().getItem(OtherItem.class, getData().getOtherItem());
  }
  /**
    Set the associated item. Null is not allowed.
    @param other The other item
    @throws PermissionDeniedException If the logged in user 
      doesn't have write permission
    @throws InvalidDataException If the other item is null
    @throws BaseException If there is another error
  */
  public void setOtherItem(OtherItem other)
    throws PermissionDeniedException, InvalidDataException, BaseException
  {
    checkPermission(Permission.WRITE);
    if (otherItem == null) throw new InvalidUseOfNullException("otherItem");
    getData().setOtherItem(otherItem.getData());
  }

  /**
    Create a child item for this any item.
    @return The new <code>ChildItem</code> object
    @throws PermissionDeniedException If the logged in user doesn't have
      write permission
    @throws BaseException If there is another error
  */
  public AChildItem newChildItem()
    throws PermissionDeniedException, BaseException
  {
    checkPermission(Permission.WRITE);
    return AChildItem.getNew(getDbControl(), this);
  }
  
  /**
    Get a query that will return all child items for this any item.
    @return An {@link ItemQuery} object
  */
  public ItemQuery<AChildItem> getChildItems()
  {
    return AChildItem.getQuery(this);
  }

}