/*
* Copyright (C) 2005-2012 BetaCONCEPT Limited
*
* This file is part of Astroboa.
*
* Astroboa is free software: you can redistribute it and/or modify
* it under the terms of the GNU Lesser General Public License as published by
* the Free Software Foundation, either version 3 of the License, or
* (at your option) any later version.
*
* Astroboa 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 Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public License
* along with Astroboa. If not, see <http://www.gnu.org/licenses/>.
*/
package org.betaconceptframework.astroboa.api.model.definition;
import java.util.Locale;
import java.util.Map;
import org.betaconceptframework.astroboa.api.model.ComplexCmsProperty;
import org.betaconceptframework.astroboa.api.model.SimpleCmsProperty;
import org.betaconceptframework.astroboa.api.model.ValueType;
/**
* Base interface for complex content object property definitions.
*
* <p>
* Contains common methods of a definition of a
* {@link ComplexCmsProperty complex property}.
* </p>
*
* <p>
* Complex property definition contains one or more
* property definitions and represents a group of (usually) common property
* definitions among several or all content object types. Therefore,
* implementation of this interface should permit the definition of a complex
* property as a stand alone definition which can be referred by
* any content object type definition or another complex property
* definition.
* </p>
*
* <p>
* Astroboa implementation uses a stand alone XML schema <code>complexType</code>
* element which must extend Astroboa complex xml type <code>complexCmsProperty</code>
* to define a complex property.
*
* <pre>
*<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
* targetNamespace="http://www.betaconceptframework.org/schema/astroboa/web/statisticType"
* xmlns:bccmsmodel="http://www.betaconceptframework.org/schema/astroboa/model">
*
* <xs:import
* namespace="http://www.betaconceptframework.org/schema/astroboa/model"
* schemaLocation="http://www.betaconceptframework.org/schema/astroboa/astroboa-model-{version}.xsd" />
*
* <xs:complexType {@link CmsDefinition#getName() name}="statistic"
* <{@link LocalizableCmsDefinition xs:annotation}>
* <xs:documentation xml:lang="en">Content Object Statistics</xs:documentation>
* </xs:annotation>
* <xs:complexContent>
* <xs:extension base="bccmsmodel:complexCmsProperty">
* <xs:sequence>
* <xs:element {@link CmsDefinition#getName() name}="viewCounter" {@link CmsPropertyDefinition#isMandatory() minOccurs}="0" {@link CmsPropertyDefinition#isMultiple() maxOccurs}="1"
* {@link CmsDefinition#getValueType() type}="xs:long" >
* <{@link LocalizableCmsDefinition xs:annotation}>
* <xs:documentation xml:lang="en">View Counter</xs:documentation>
* </xs:annotation>
* </xs:element>
* </xs:sequence>
* </xs:extension>
* </xs:complexContent>
* </xs:complexType>
*</xs:schema>
* </pre>
*
* and in order to define it in terms of a content object type definition an XML
* Schema <code>element</code> is used
*
* <pre>
* <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
* xmlns:administrativeMetadataType="http://www.betaconceptframework.org/schema/astroboa/admin/administrativeMetadataType">
*
* <xs:import
* namespace="http://www.betaconceptframework.org/schema/astroboa/admin/administrativeMetadataType"
* schemaLocation="administrativeMetadataType-3.0.0.GA.xsd" />
*
* <xs:element name="newsItem">
* <xs:annotation>
* <xs:documentation xml:lang="en" >News Item</xs:documentation>
* </xs:annotation>
* <xs:complexType>
* <xs:complexContent>
* <xs:extension base="bccmsmodel:contentObject">
* <xs:sequence>
* <xs:element {@link CmsDefinition#getName() name}="statistic:statistic" type="statistic" {@link CmsPropertyDefinition#isMandatory() minOccurs}="1" {@link CmsPropertyDefinition#isMultiple() maxOccurs}="1"/>
* </xs:sequence>
* </xs:extension>
* </xs:complexContent>
* </xs:complexType>
* </xs:element>
*</xs:schema>
* </pre>
*
* The above xml schemas define a content object type definition named
* <code>newsItem</code> which contains a complex property named
* <code>statistic</code> which by its turn contains a simple property named
* <code>viewCounter</code>.
* </p>
*
* @author Gregory Chomatas (gchomatas@betaconcept.com)
* @author Savvas Triantafyllou (striantafyllou@betaconcept.com)
*
* @see <a href="http://www.betaconceptframework.org/schema/astroboa/astroboa-model-{version}.xsd">Astroboa model XML schema
* for more on <code>complexCmsProperty</code> complex type. </a>
*
*/
public interface ComplexCmsPropertyDefinition extends CmsPropertyDefinition {
/**
* Returns a map of {@link CmsPropertyDefinition definitions} of all child
* property definitions of complex property.
*
* Map's key is complex property definition's
* {@link CmsDefinition#getName() name}.
*
* @return Child property definitions map.
*/
Map<String, CmsPropertyDefinition> getChildCmsPropertyDefinitions();
/**
* <p>
* Returns a map of {@link CmsPropertyDefinition definitions} of all child
* property definitions of complex property, sorted by definition's
* {@link CmsPropertyDefinition#getOrder() order} and THEN
* by localized labels for specified locale.
*</p>
*
*<p>
* Sorting order is ascending and it is not configurable.
*</p>
* @param locale
* Locale value as defined in {@link Localization}. In case
* where <code>locale</code> is blank (empty or null),
* {@link Locale#ENGLISH English} locale will be
* used.
* @return Child property definitions map sorted by definition's order and localized labels.
*/
Map<String, CmsPropertyDefinition> getSortedChildCmsPropertyDefinitionsByAscendingOrderAndLocale(
String locale);
/**
* <p>
* Returns a map of {@link CmsPropertyDefinition definitions} of all child
* property definitions of complex property, sorted by definition's
* {@link CmsPropertyDefinition#getOrder() order} and THEN by
* {@link CmsDefinition#getValueType() value type} and finally by localized labels by specified locale.
* </p>
*
*<p>
* Sorting order is ascending and it is not configurable.
*</p>
*
* <p>
* {@link ValueType ValueType} comparison is performed by the following order,
* where the first in the list, is considered greater than the others. This order
* is not configurable.
* <ul>
* <li>{@link SimpleCmsPropertyDefinition simple property definitions}
* <li>{@link BinaryPropertyDefinition binary definitions}
* <li>{@link ComplexCmsPropertyDefinition complex property definitions}
* </ul>
* </p>
*
* <p>
* For properties of the same type, ordering is performed according to their
* localized labels.
* </p>
* @param locale
* Locale value as defined in {@link Localization}. In case
* where <code>locale</code> is blank (empty or null),
* {@link Locale#ENGLISH English} locale will be
* used.
* @return Child property definitions map sorted by definition's order and localized labels.
*/
Map<String, CmsPropertyDefinition> getSortedChildCmsPropertyDefinitionsByAscendingOrderAndValueTypeAndLocale(
String locale);
/**
* Returns child property definition for the specified
* <code>childCmsPropertyPath</code>.
*
* Path is relative to this definition.
*
* @param childCmsPropertyPath
* A period-delimited string describing the path to the child property starting
* from this definition.
*
* @return Child property definition or <code>null</code> if none has been found.
*/
CmsPropertyDefinition getChildCmsPropertyDefinition(
String childCmsPropertyPath);
/**
* Check if there are any child property definitions at all.
*
* @return <code>true</code> if there is at least one child property
* definition, <code>false</code> otherwise.
*/
boolean hasChildCmsPropertyDefinitions();
/**
* Checks if there is a child property definition for the specified path.
*
* Path is relative to this definition.
*
* @param childCmsPropertyPath
* A period-delimited string describing the path to the child property starting
* from this definition.
*
* @return <code>true</code> if a child property definition exists for the
* specified path, <code>false</code> otherwise.
*/
boolean hasChildCmsPropertyDefinition(String childCmsPropertyPath);
/**
* Returns a comma delimited string which contains one or more
* {@link SimpleCmsProperty simple property} paths whose
* value can be used as a label for {@link ComplexCmsProperty complex property}
* of this definition instead of its system name or its display name which is provided
* in the annotation tag in its schema.
*
* @return Value provided in XML schema for attribute
* bccsmodel:labelElementPath, <code>null</code> if no value is provided
*/
String getPropertyPathsWhoseValuesCanBeUsedAsALabel();
/**
* Checks if this definition is a global one, that is can be attached at runtime to any
* content object.
*
* @return <code>true</code> if this definition can be used as an aspect, <code>false</code> otherwise
*/
boolean isGlobal();
/**
* Get the number of levels of the definition hierarchy tree.
*
* The depth is zero based, 0 stands for the current definition.
*
* The depth of a {@link ComplexCmsPropertyDefinition} is augmented by one if the definition
* has at least one child {@link ComplexCmsPropertyDefinition} or {@link BinaryPropertyDefinition}.
* A {@link BinaryPropertyDefinition} is considered a complex property in the sense that it contains
* several internal properties beside the actual binary value.
*
* @return Number of the levels of the definition hierarchy tree.
*/
int getDepth();
}