Package lumis.doui.source

Class Source<F extends ISourceField>

  • Type Parameters:
    F - the interface all fields of this source must implement.
    Direct Known Subclasses:
    TabularSource
    @StableMinor(version="16.0",
             sinceVersion="4.0")
public abstract class Source<F extends ISourceField>
extends java.util.Observable
    The base implementation of a doui data source.
    Since:
    4.0.0
    Version:
    $Revision: 25809 $ $Date: 2023-07-04 15:23:22 -0300 (Tue, 04 Jul 2023) $

    • Field Detail

      • SOURCE_READ_DATA_ON_DEMAND

        public static final java.lang.String SOURCE_READ_DATA_ON_DEMAND
        See Also:
        Constant Field Values

      • SOURCE_READ_DATA_NEVER

        public static final java.lang.String SOURCE_READ_DATA_NEVER
        See Also:
        Constant Field Values

      • SOURCE_READ_DATA_ALWAYS

        public static final java.lang.String SOURCE_READ_DATA_ALWAYS
        See Also:
        Constant Field Values

      • id

        protected final java.lang.String id

      • metaDataSourceId

        protected final java.lang.String metaDataSourceId

      • connectionId

        protected final java.lang.String connectionId

      • parameters

        protected final java.util.Map<java.lang.String,​java.lang.Object> parameters

      • sourceDefinitionNode

        protected final org.w3c.dom.Node sourceDefinitionNode

      • administrationInterfaceId

        protected final java.lang.String administrationInterfaceId

      • addInterfaceId

        protected final java.lang.String addInterfaceId

      • editInterfaceId

        protected final java.lang.String editInterfaceId

      • detailsInterfaceId

        protected final java.lang.String detailsInterfaceId

      • fieldsMap

        protected final java.util.Map<java.lang.String,​F extends ISourceField> fieldsMap
        A map of field id to the ISourceField instance. Changes to this map automatically reflects in the fields list. The fields list has the order the entries were put in this map.
        Since:
        4.0.4
        See Also:
        fields

      • fields

        protected final java.util.List<F extends ISourceField> fields
        A unmodifiable list of this source's fields. This list automatically reflects the changes done in fieldsMap. The order of fields in this list is the same as the order the fields were put in fieldsMap.
        Since:
        4.0.4
        See Also:
        fieldsMap

      • load

        protected boolean load

      • readData

        protected java.lang.String readData

      • primaryNameSourceField

        protected F extends ISourceField primaryNameSourceField

      • introductionSourceField

        protected F extends ISourceField introductionSourceField

      • keywordsSourceField

        protected F extends ISourceField keywordsSourceField

    • Method Detail

      • isAdministrationInterface

        protected boolean isAdministrationInterface​(IServiceInterface serviceInterface)
        Returns true if the given service interface is the main administration interface for this source.
        Parameters:
        serviceInterface - the service interface.
        Returns:
        true if the given service interface is the main administration interface for this source, false otherwise.
        Since:
        4.0.6

      • readFieldsIntoFieldsMap

        protected void readFieldsIntoFieldsMap()
                                throws PortalException
        Reads this source's fields into the fieldsMap. The order the source fields are put in the map will define the order the fields will be in the fields list. This order may affect some field processing.
        Throws:
        PortalException - if an error was found while reading the source's fields into the fields map.
        Since:
        4.0.4

      • createCustomSourceField

        protected F createCustomSourceField​(org.w3c.dom.Node fieldNode)
                             throws PortalException
        Factory method for creating a custom source field. A source field is a field whose class name is specified in its definition.
        Parameters:
        fieldNode - the field definition.
        Returns:
        the field instance, or null if the field is not a custom source field.
        Throws:
        PortalException
        Since:
        4.0.6

      • createSourceField

        protected F createSourceField​(org.w3c.dom.Node fieldNode)
                       throws PortalException
        Factory method for creating a source field instance that corresponds to the field node given. This method instantiate and returns the source field, without initializing it.
        Parameters:
        fieldNode - the field node.
        Returns:
        the ISourceField created, or null if no field should be created for this node.
        Throws:
        PortalException
        Since:
        4.0.4
        See Also:
        createCustomSourceField(Node)

      • createSourceFilter

        public ISourceFilter createSourceFilter​(org.w3c.dom.Node filterNode)
                                 throws PortalException
        Creates a source filter for the given filter definition node. The node may be a filters or filter node.
        Parameters:
        filterNode - the filter definition node.
        Returns:
        the source filter.
        Throws:
        PortalException
        Since:
        4.0.5

      • createDefaultFilterInstance

        protected ISourceFilter createDefaultFilterInstance()
        Creates and returns a source filter instance to be used as default to filter nodes.
        Returns:
        the created instance.
        Since:
        4.0.5

      • createDefaultCompositeFilterInstance

        protected ISourceFilter createDefaultCompositeFilterInstance()
        Creates and returns a source filter instance to be used as default to filters nodes.
        Returns:
        the created instance.
        Since:
        4.0.5

      • getFilter

        public ISourceFilter getFilter()
        Returns the filter for this source. The filter must be initialized with the appropriated parameters before each use.
        Returns:
        the filter or null if this source has no filter.
        Since:
        4.0.5

      • getId

        public java.lang.String getId()
        Returns the source id.
        Returns:
        Since:
        4.0.11

      • getParameterClass

        public java.lang.Class<?> getParameterClass​(java.lang.String parameterName)
        Returns the class given a parameter name.

        The class is determined by the field type where the fieldId equals the parameter name.

        Parameters:
        parameterName -
        Returns:
        Since:
        4.0.11

      • setParameterValue

        @Deprecated
public final void setParameterValue​(java.lang.String parameterName,
                                    java.lang.Object value)
        Deprecated.
        Since 7.1.0 replaced by setParameterValue(String, Object, String) to allow proper conversion of value to string. This method is kept only for backwards compatibility with callers and is no longer called by the portal container. The final modifier has been applied to this method to force overriding methods to be adjusted to override the correct method instead of being silently ignored.
        Sets the parameter value of the source.
        Parameters:
        parameterName -
        value -
        Since:
        4.0.11

      • setParameterValue

        public void setParameterValue​(java.lang.String parameterName,
                              java.lang.Object value,
                              java.lang.String valueAsString)
        Sets a parameter value in this source.

        The source's parameter values usually affect which or how data is loaded on it.

        Parameters:
        parameterName - the parameter name.
        value - the value.
        valueAsString - the value converted to string. It is important that the string corresponds to the value, such as when another equivalent value is set its string is also equivalent to this one, and when another value is different its string is also different of this one.
        Since:
        7.1.0

      • getParameterValue

        public java.lang.Object getParameterValue​(java.lang.String parameterName)
        Returns a parameter value previously set.
        Parameters:
        parameterName -
        Returns:
        Since:
        4.0.11

      • valueChanged

        protected boolean valueChanged​(java.lang.String parameterName,
                               java.lang.String newValueAsString)
        Returns true if the current value of the parameter changed from the previous value.
        Parameters:
        parameterName - the parameter name.
        newValueAsString - the new value converted to String.
        Returns:
        true if the value changed, false otherwise.
        Since:
        7.1.0
        See Also:
        setParameterValue(String, Object, String)

      • getDefinitionNode

        @Deprecated
public org.w3c.dom.Node getDefinitionNode()
        Deprecated.
        This method may not be public in the future.
        Returns:
        Since:
        4.0.4

      • getAdministrationInterfaceId

        public java.lang.String getAdministrationInterfaceId()
        Returns the main administration interface id for this source.
        Returns:
        the main administration interface id for this source. It may be null if the source does not have a main administration interface.
        Since:
        4.0.4

      • getAddInterfaceId

        public java.lang.String getAddInterfaceId()
        Returns the default add interface id for this source.
        Returns:
        the default add interface id for this source. It may be null if the source does not have a default add interface.
        Since:
        6.0.0

      • getEditInterfaceId

        public java.lang.String getEditInterfaceId()
        Returns the default edit interface id for this source.
        Returns:
        the default edit interface id for this source. It may be null if the source does not have a default edit interface.
        Since:
        6.0.0

      • getDetailsInterfaceId

        public java.lang.String getDetailsInterfaceId()
        Returns the default details interface id for this source.
        Returns:
        the default details interface id for this source. It may be null if the source does not have a default details interface.
        Since:
        6.0.0

      • getDefaultProviderClass

        protected abstract java.lang.String getDefaultProviderClass()
                                                     throws PortalException
        Abstract method that returns the default data provider class name.
        Returns:
        Throws:
        PortalException
        Since:
        4.0.11

      • setLoad

        public void setLoad​(boolean load)
        Sets the property indicating whether this source must be loaded by its data provider.
        Parameters:
        load -
        Since:
        4.0.11

      • getLoad

        public boolean getLoad()
        Returns the load property.

        The doui framework uses this to determine whether the source should be loaded or not.

        Returns:
        Since:
        4.0.11

      • load

        public void load()
          throws PortalException
        This is where the actual loading of the source data takes place.

        The data provider is called by the source to load its data. After data is loaded, all data conversion is performed and observers are notified.

        Throws:
        PortalException
        Since:
        4.0.11

      • postProcessSource

        protected void postProcessSource()
                          throws PortalException
        Executes the post load processors associated with the current source. Note: this task was previously executed by the SourceContainer.
        Throws:
        PortalException
        Since:
        4.0.6

      • convertDataToDefinedDataTypes

        protected abstract void convertDataToDefinedDataTypes()
                                               throws PortalException
        Converts the data in this source to the values that should be used according to its fields definitions.
        Throws:
        PortalException
        Since:
        4.0.4

      • getReadData

        public java.lang.String getReadData()
        Returns:
        Returns the loadType.

      • setReadData

        public void setReadData​(java.lang.String loadType)
        Returns the load type of the source.
        Parameters:
        loadType - The loadType to set.

      • getFiltersNode

        public org.w3c.dom.Node getFiltersNode()
                                throws PortalException
        Returns the "filters" node of the source.

        A null value is returned if no filters are specified.

        Returns:
        Throws:
        PortalException
        Since:
        4.0.11

      • applyPostLoadFilters

        public void applyPostLoadFilters()
                          throws PortalException
        Apply the filters specified in this source to its data. This is an utility method for data providers that does not support filtering during the source load operation. After loading the source's data without filtering it, the data provider may call this method for the source to remove data that does not attend to the filters specified.

        Data providers that may provide significant quantity of data should implement its own filtering during load instead of using this method, to prevent unnecessary use of server's memory and cpu.

        Throws:
        java.lang.UnsupportedOperationException - if the source's implementation for this method does not support the filters specified.
        PortalException
        See Also:
        IDataProvider.loadData(lumis.portal.SessionConfig, Source, lumis.util.ITransaction)

      • getSourceContext

        public ISourceContext getSourceContext()
        Returns this source's context.
        Returns:
        this source's context.

      • getDouiContext

        public DouiContext getDouiContext()
        Returns this source's doui context.
        Returns:
        this source's doui context. May be null if this source does not belong to a doui context.

      • getSourceContainer

        public SourceContainer getSourceContainer()
        Returns this source's container.
        Returns:
        this source's container. May be null if this source does not belong to a source container.

      • getDistinct

        public boolean getDistinct()
                    throws PortalException
        Returns the distinct property of the source.

        The data provider reads this property to determine how to retrieve data.

        Returns:
        Throws:
        PortalException
        Since:
        4.0.11

      • getMetaDataSourceId

        public java.lang.String getMetaDataSourceId()
        Returns the metaDataId.
        Returns:
        Returns the metaDataId.

      • getField

        public F getField​(java.lang.String fieldId)
        Returns the field with the given id.
        Parameters:
        fieldId - the field's id.
        Returns:
        the field with the given id, or null if there is no field with such id.
        Since:
        4.0.4

      • getFields

        public java.util.List<F> getFields()
        Returns a unmodifiable list of the fields in this source.
        Returns:
        a unmodifiable list of the fields in this source.
        Since:
        4.0.4

      • getPrimaryNameField

        public F getPrimaryNameField()
        Returns the field that is the primary name of this source.
        Returns:
        the field that is the primary name of this source, or null if this source has no primary name field.
        Since:
        4.0.4

      • getIntroductionField

        public F getIntroductionField()
        Returns the field that is the introduction of this source.
        Returns:
        the field that is the introduction of this source, or null if this source has no introduction field.
        Since:
        4.0.4

      • getIntroductionImageField

        public F getIntroductionImageField()
        Returns the field that is the introduction image of this source.
        Returns:
        the field that is the introduction image of this source, or null if this source has no introduction image field.
        Since:
        8.1.0

      • getPublishStartDateField

        public F getPublishStartDateField()
        Returns the field that is the publish start date of this source.
        Returns:
        the field that is the publish start date of this source, or null if this source has no publish start date field.
        Since:
        8.1.0

      • getKeywordsField

        public F getKeywordsField()

      • getDouiHyperlinkItemParameterField

        public DouiHyperlinkItemParameterField getDouiHyperlinkItemParameterField()
        Returns the information about the field that is associated with the item id page parameter.
        Returns:
        the information about the field that is associated with the item id page parameter.
        Since:
        4.0.6
        See Also:
        PageConfig.PAGE_PARAMETER_ITEMID, DouiHyperlinkItemParameterField

      • getHyperlinkDefaultParameters

        public java.util.Collection<java.lang.String> getHyperlinkDefaultParameters()
        Returns the default parameters that should be used when creating a hyperlink url from this source.
        Returns:
        a collection with the default parameter names.
        Since:
        4.2.0

      • isDetails

        public boolean isDetails()
        Returns whether this source is the main source for a details interface, intended for obtaining the detailed information of a data.
        Returns:
        true if this source is a details source, false otherwise.
        Since:
        7.0.1

      • getBigDataPersister

        public <S extends Source<?>> ISourceBigDataPersister<S> getBigDataPersister()
        Returns the ISourceBigDataPersister implementation to be used for this source.
        Returns:
        the ISourceBigDataPersister implementation.
        Since:
        8.1.0

      • getDefaultBigDataPersister

        protected <S extends Source<?>> ISourceBigDataPersister<S> getDefaultBigDataPersister()
        Returns the default ISourceBigDataPersister implementation to be used for this source if the big data persisting is not disabled and no specific persister class is configured for this source.

        This method is called by getBigDataPersister() when the default is to be used.

        Returns:
        the default ISourceBigDataPersister implementation.
        Since:
        8.1.0

      • isRenderDataChangedNotificationEnabled

        public boolean isRenderDataChangedNotificationEnabled()
        Returns whether render data changed notification is enabled for operations done by this source object.
        Returns:
        true if render data changed notification is enabled, false otherwise.
        Since:
        10.4.0
        See Also:
        setRenderDataChangedNotificationEnabled(boolean)

      • setRenderDataChangedNotificationEnabled

        public void setRenderDataChangedNotificationEnabled​(boolean renderDataChangedNotificationEnabled)
        Sets whether render data changed notification will be generated by this source object on corresponding operations.

        By default render data changed notification is enabled.

        Parameters:
        renderDataChangedNotificationEnabled - true to enable render data changed notification on this source object or false to disable it.
        Since:
        10.4.0
        See Also:
        isRenderDataChangedNotificationEnabled()

      • readData

        public final java.util.List<ISourceData> readData​(java.lang.String... itemIds)
                                           throws PortalException
        Returns the data corresponding to the given itemIds.

        This method is a convenience overload that calls readData(Collection).

        Parameters:
        itemIds - the item identifiers of the data to be returned.
        Returns:
        a list of ISourceData objects that corresponds to the given itemIds. If no data is found, an empty list is returned.
        Throws:
        PortalException
        Since:
        10.4.0

      • readData

        public java.util.List<ISourceData> readData​(java.util.Collection<java.lang.String> itemIds)
                                     throws PortalException
        Returns the data corresponding to the given itemIds.

        The implementation of this method in Source throws an UnsupportedOperationException. This method should be overridden by source implementations that provides this functionality.

        Parameters:
        itemIds - the item identifiers of the data to be returned.
        Returns:
        a list of ISourceData objects that corresponds to the given itemIds. If no data is found, an empty list is returned.
        Throws:
        PortalException
        Since:
        10.4.0

      • scheduleIndexData

        public void scheduleIndexData​(java.util.Collection<java.lang.String> itemIds)
                       throws PortalException
        Schedules the indexing of the data that corresponds to the specified item identifiers. Due to the non-transactional nature of big data, this method must schedule the actual indexing for after the transaction commit.

        This method is called by the source's standard operations that add/update/delete data. So typically, this method is only needed to be called from outside the source when the data is changed outside it or something else make it necessary to re-index the data.

        The implementation of this method in Source uses readData(Collection) to read the data to be indexed and getBigDataPersister() to apply it to the big data.

        Parameters:
        itemIds - the item identifiers.
        Throws:
        PortalException
        Since:
        10.4.0

      • doAddData

        protected ISourceAddDataResult doAddData​(IParameters data)
                                  throws PortalException
        Adds the data to the persistence.

        This method is called by addData(Object) and is to be overridden by sources that supports add operation and uses the default addData implementation.

        The implementation of this method in Source throws UnsupportedOperationException.

        Parameters:
        data - the data given to addData(Object), converted to IParameters if necessary.
        Returns:
        the result object to be returned by addData(Object).
        Throws:
        java.lang.UnsupportedOperationException - if add operation is not supported on this source.
        PortalException
        Since:
        10.4.0

      • getUpdateDataItemId

        protected java.lang.String getUpdateDataItemId​(IParameters data)
        Returns the item identifier of a data being updated.
        Parameters:
        data - the data.
        Returns:
        the item identifier.
        Since:
        10.4.0

      • postUpdateFieldData

        protected void postUpdateFieldData​(SourcePostUpdateDataEvent event)
                            throws PortalException
        Called after data is updated in the persistence.

        The default implementation of this method calls ISourceField#postUpdate(SourcePreUpdateDataEvent) on each field of this source.

        Parameters:
        event - the event that contains information about the update operation.
        Throws:
        PortalException
        Since:
        10.4.0
        See Also:
        updateData(Object)

      • doUpdateData

        protected ISourceUpdateDataResult doUpdateData​(IParameters data)
                                        throws PortalException
        Updates the data in the persistence.

        This method is called by updateData(Object) and is to be overridden by sources that supports update operation and uses the default updateData implementation.

        The implementation of this method in Source throws UnsupportedOperationException.

        Parameters:
        data - the data given to updateData(Object), converted to IParameters if necessary.
        Returns:
        the result object to be returned by updateData(Object).
        Throws:
        java.lang.UnsupportedOperationException - if update operation is not supported on this source.
        PortalException
        Since:
        10.4.0

      • doDeleteDataByItemIds

        protected void doDeleteDataByItemIds​(java.util.Collection<java.lang.String> itemIds)
                              throws PortalException
        Deletes the data in the persistence.

        This method is called by deleteDataByItemIds(Collection) and is to be overridden by sources that supports delete operation and uses the default deleteData implementation.

        The implementation of this method in Source throws UnsupportedOperationException.

        Parameters:
        itemIds - the item identifiers of data to be deleted.
        Throws:
        java.lang.UnsupportedOperationException - if delete operation is not supported on this source.
        PortalException
        Since:
        10.4.0