Class ItemContext


  • public class ItemContext
    extends Object
    This item is a helper class for client applications when they need to store information about the current context for plugins that needs to find out the current context of the running client application. It is optional to use this class and it is recommended that plugins and client applications that expects to find context information also can handle situations without any context information. Some of the settings in this objects are saved in the database, some not.

    Typical example for using this class are:

    A client application storing list/table settings

    SessionControl sc = ...
    ItemContext current = sc.getCurrentContext(Item.SAMPLE);
    current.setRowsPerPage(50);
    current.setPage(0);
    current.setSortProperty("name");
    current.setSortDirection(SortDirection.DESC);
    current.setPropertyFilter(
          new PropertyFilter("name", Operator.LIKE, "Nicklas%", Type.STRING)
       );
    ItemQuery query = Sample.getQuery();
    current.configureQuery(query, true);
    // The query will now return the 50 first samples with a
    // a name starting with 'Nicklas' sorted in descending order
    

    A client application using filter information when creating new items

    SessionControl sc = ...
    DbControl dc = sc.newDbControl();
    ItemContext current = sc.getCurrentContext(Item.SAMPLE);
    Sample sample = Sample.getNew(dc);
    if (current.getPropertyValue("name") != null)
    {
       sample.setName(current.getPropertyValue("name"));
    }
    // The name is now 'Nicklas%'
    

    Plugin finds out which items in a list has been selected

    SessionControl sc = ...
    ItemContext current = sc.getCurrentContext(Item.SAMPLE);
    ItemQuery query = Sample.getQuery();
    Set selected = current.getSelected();
    if (selected != null && selected.size() > 0)
    {
       query.restrict(
             Restrictions.in(Hql.property("id"), 
             Expressions.parameter("selected", selected, Type.INT))
          );
    )
    // The query will now return the selected items only
    

    An import plugin asks client application for a file with a specific file type

    public RequestInformation getRequestInformation(GuiContext context, String command)
       throws BaseException
    {
       RequestInformation requestInformation = null;
       if (command.equals(Request.COMMAND_CONFIGURE_PLUGIN))
       {
          requestInformation = getConfigurePluginParameters(context);
       }
       else if (command.equals(Request.COMMAND_CONFIGURE_JOB))
       {
          requestInformation = getConfigureJobParameters(context);
          ItemContext fileContext = sc.getCurrentContext(Item.FILE);
          fileContext.setPropertyFilter(FileType.getPropertyFilter(FileType.REPORTER));
       }
       return requestInformation;
    }
    
    Version:
    2.0
    Author:
    Nicklas
    See Also:
    SessionControl.getCurrentContext(Item), SessionControl.saveCurrentContextAs(Item, String, boolean, boolean)
    Last modified
    $Date: 2020-05-19 14:24:30 +0200 (Tue, 19 May 2020) $
    • Field Detail

      • DEFAULT_NAME

        public static final String DEFAULT_NAME
        This is the name of the default context which is automatically saved when a user is logging out. A client application shouldn't use this name for other named contexts that it wants to reload in the future.
        See Also:
        Constant Field Values
      • name

        private final String name
      • itemType

        private final Item itemType
      • subContext

        private final String subContext
      • contextId

        private int contextId
      • itemId

        private int itemId
      • noPaging

        private boolean noPaging
      • rowsPerPage

        private int rowsPerPage
      • page

        private int page
      • numFilterRows

        private int numFilterRows
      • sortProperty

        private String sortProperty
      • message

        private String message
      • query

        private Query query
      • propertyInspector

        private Filter<String> propertyInspector
      • NO_AUTO_JOIN_PREFIXES

        private static final Set<String> NO_AUTO_JOIN_PREFIXES
    • Constructor Detail

      • ItemContext

        public ItemContext​(String sortProperty,
                           ItemContext.SortDirection sortDirection,
                           int rowsPerPage,
                           int page)
        Create a new context.
        Parameters:
        sortProperty - The property used to sort a list
        sortDirection - If the items should be sorted in ascending or descending order
        rowsPerPage - The number of rows to display on a single page
        page - The page number of the currently displayed page, starting at 0
      • ItemContext

        ItemContext​(Item itemType,
                    String subContext,
                    String name)
        Create a new empty context.
      • ItemContext

        ItemContext​(ContextData context)
        Create a new context from a loaded database object.
      • ItemContext

        ItemContext​(Item itemType,
                    ItemListSyncFilterData syncFilter)
        Initialize the context from an item list synchronization filter. Note that this creates a special context used for implementing the query functionality of a SyncFilter. It should not be used for representing context in a GUI. To do this start with a regular context and the use copyFromSyncFilter(ItemListSyncFilterData) instead.
        Since:
        3.5
    • Method Detail

      • getData

        ContextData getData​(String name,
                            UserData user,
                            ClientData client,
                            boolean isPublic)
        Create a new database context object from this context.
        Parameters:
        name - The name to use, or null if the current name should be used
        user - The user that should own the context object
        client - The client application currently in use
        isPublic - If the context should be public or not
      • storePropertyFilters

        private void storePropertyFilters​(Map<String,​PropertyFilterData> filterData)
        Store the current property filters and save them in the give filterData map.
      • getItemType

        public Item getItemType()
        Get the type of item this object is storing context for.
      • getSubContext

        public String getSubContext()
        Get the sub-context name of this context.
      • getName

        public String getName()
        Get the name of this context.
      • getContextId

        public int getContextId()
        Get the database ID of this context. Can be used to load contexts
        Returns:
        The database ID of the context, or 0 if it hasn't been saved to the database
        Since:
        2.4
      • getId

        public int getId()
        Get the ID of the current item in this context.
        Returns:
        The ID of the item, or 0 if no item is current
      • setId

        public void setId​(int id)
        Set the ID of the current item in this context. This property is stored in the database.
        Parameters:
        id - The ID of the item, or 0 if no item is current
      • getRowsPerPage

        public int getRowsPerPage()
        Get the number of rows the current table page is displaying.
        Returns:
        The number of rows
      • setRowsPerPage

        public void setRowsPerPage​(int rowsPerPage)
        Set the number of rows the current table page should show. This property is stored in the database.
        Parameters:
        rowsPerPage - The number of rows to show on a page
      • getPage

        public int getPage()
        Get the current table page.
        Returns:
        The number of the page, starting at 0
      • setPage

        public void setPage​(int page)
        Set the current table page. This property is stored in the database.
        Parameters:
        page - The number of the page, starting at 0
      • getFilterRows

        public int getFilterRows()
        Get the number of filter rows to display on the list page.
        Since:
        3.5
      • addFilterRows

        public int addFilterRows​(int numRows)
        Add filter rows to the table.
        Parameters:
        numRows - The number of rows to add, must be greater than 0
        Returns:
        The number of filter rows after adding
        Since:
        3.5
      • removeFilterRow

        public int removeFilterRow​(int filterIndex)
        Remove all filters from the specified filter row. Rows with a higher index are shifted down by one step.
        Parameters:
        filterIndex - A value between 0 and number of filter rows (-1)
        Returns:
        The number of filter rows after removing
        Since:
        3.5
      • getSortProperty

        public String getSortProperty()
        Get the name of the property the current listing is sorted by. If multiple properties are used for sorting they are separated by a comma. Each property may also be prefixed by a '+' or '-' to override the global sort direction.
      • setSortProperty

        public void setSortProperty​(String sortProperty)
        Set the name of the property that the current listing is sorted by. If you want to sort by multiple properties, separate them with a comma. By default, each property uses the same sort direction (getSortDirection(), but this can be overridden by using '+' or '-' as a prefix for a property. This property is stored in the database.
        Parameters:
        sortProperty - The name of the property
      • getSortDirection

        public ItemContext.SortDirection getSortDirection()
        If the items are sorted in ascending or descending order.
      • setSortDirection

        public void setSortDirection​(ItemContext.SortDirection sortDirection)
        Set the sort direction (ascending or descending) of the current listing. This property is stored in the database.
        Parameters:
        sortDirection - The sort direction
      • getSortOrder

        public Order getSortOrder()
        Get the current sort property as an Order instance. If multiple properties are used for sorting, this method only returns the first property.
        Returns:
        An Order instance, or null if no sort order has been specified
      • getMessage

        public String getMessage()
        Get a message that should be displayed by a client application as soon as it is appropriate to do so. Typically, the configureQuery(DbControl, EntityQuery, boolean) sets an error message if it couldn't configure the query for some reason.
      • setMessage

        public void setMessage​(String message)
        Set a message to be displayed by a client application as soon as it is appropriate to do so. Typically, the configureQuery(DbControl, EntityQuery, boolean) sets an error message if it couldn't configure the query for some reason. This property is not stored in the database.
        Parameters:
        message - The message
      • getInclude

        public Set<Include> getInclude()
        Get a Set object to specify Include options for a query. This property is stored in the database.
        See Also:
        EntityQuery
      • setItemPermission

        public void setItemPermission​(Permission permission)
        Specify the permission the logged in user must have for items returned by a query. This property is not stored in the database.
        See Also:
        EntityQuery.setItemPermission(Permission)
      • getItemPermission

        public Permission getItemPermission()
        The permission the logged in user must have for items returned by a query. This property is not stored in the database.
        See Also:
        EntityQuery.getItemPermission()
      • getSelected

        public Set<Integer> getSelected()
        Get a Set object to specify the ID:s of all items that are currently selected. This property is not stored in the database.
      • setPropertyFilter

        public void setPropertyFilter​(PropertyFilter filter)
        Set a property filter. If a filter for the same property already exists it is replaced by the new filter. Note that each property may hold two filters, one primary and one temporary. Only primary filters are stored in the database.
        Parameters:
        filter - The new property filter
        See Also:
        PropertyFilter.isTemporary()
      • getPropertyFilter

        public PropertyFilter getPropertyFilter​(String property,
                                                int filterRow)
        Get a filter for a property. If the given property has a temporary filter, it is returned, otherwise it's primary filter is returned.
        Parameters:
        property - The name of the property
        filterRow - The index of the filter row should be between 0 and number of filter rows (-1)
        Returns:
        A PropertyFilter object or null if no filter exists
        Since:
        3.5
      • getPropertyFilters

        public Collection<PropertyFilter> getPropertyFilters()
        Get a collection of all property filters stored in this context. The returned collection may contain both primary and temporary filters, but only one filter for each property.
        Returns:
        A Collection containsing PropertyFilter objects or null
      • getPropertyFilters

        public Collection<PropertyFilter> getPropertyFilters​(int filterRow)
        Get a collection of all property filters stored in this context for a given filter row. The returned collection may contain both primary and temporary filters, but only one filter for each property.
        Parameters:
        filterRow - The index of the filter row should be between 0 and number of filter rows (-1)
        Returns:
        A Collection containsing PropertyFilter objects or null
        Since:
        3.5
      • getNumPropertyFilters

        public int getNumPropertyFilters()
        Get the total number of property filters stored in this context.
        Since:
        2.12
      • getNumPropertyFilters

        public int getNumPropertyFilters​(int filterRow)
        Get the number of property filters stored in this context for the given filter row.
        Parameters:
        filterRow - The index of the filter row should be between 0 and number of filter rows (-1)
        Since:
        3.5
      • hasPropertyFilter

        public boolean hasPropertyFilter​(String property)
        Checks if there is a filter for the given property regardless of filter row. Shortcut for checking each filter row at a time and getPropertyFilter(String, int) for non-null.
        Parameters:
        property - The name of the property
        Returns:
        TRUE if at least one filter exists, FALSE if not
        Since:
        3.5
      • getPropertyValue

        public String getPropertyValue​(String property,
                                       int filterRow)
        Get the value of a property filter on the given filter row. It is a shortcut for getPropertyFilter(property, filterRow).getValue() but also handles the case of a non-existing filter for the specfied property.
        Parameters:
        property - The name of the property
        filterRow - The index of the filter row should be between 0 and number of filter rows (-1)
        Returns:
        The value as a string
        Since:
        3.5
      • removePropertyFilter

        public void removePropertyFilter​(String property,
                                         int filterRow)
        Remove a property filter on the given filter row. This method will remove both a primary and a temporary filter.
        Parameters:
        property - The name of the property
        filterRow - The index of the filter row should be between 0 and number of filter rows (-1)
        Since:
        3.5
      • removeTemporaryFilter

        public void removeTemporaryFilter​(String property)
        Remote a temporary filter for the given property on filter row 0.
        Since:
        2.16
        See Also:
        removeTemporaryFilter(String, int)
      • removeTemporaryFilter

        public void removeTemporaryFilter​(String property,
                                          int filterRow)
        Remote a temporary filter for the given property. If a primary filter exists it will now be the effective filter.
        Parameters:
        property - The name of the property
        filterRow - The index of the filter row should be between 0 and number of filter rows (-1)
        Since:
        3.5
      • getPropertyObject

        public <T> T getPropertyObject​(String property)
      • removeAllPropertyFilters

        public void removeAllPropertyFilters()
        Remove all property filter from this context.
      • removeAllTemporaryFilters

        public void removeAllTemporaryFilters()
        Remove all temporary filters.
        Since:
        2.16
      • getFilterRestriction

        public Restriction getFilterRestriction​(String property,
                                                int filterRow,
                                                DbControl dc,
                                                EntityQuery query)
        Create a restriction from a property filter on the given filter row.
        Parameters:
        property - The property
        filterRow - The index of the filter row should be between 0 and number of filter rows (-1)
        dc - A DbControl that should be used if database access is needed
        query - The query that the filter is going to be used in (can be null for most properties)
        Returns:
        A restriction, or null if no filter is active for the given property
        Since:
        3.5
      • setRecent

        @Deprecated
        public void setRecent​(BasicItem item,
                              int maxInList)
        Deprecated.
        In 3.15, use setRecent(Item, BasicItem, int) which support 'null' entries
        Add an item to the "recently used items" list. Each type of item has their own list which may contain at most maxInList items.

        Note! The lists are stored as string of colon-separated ID:s in the setting given by the item type. For example the recently used protocols are found in the setting: getSetting("PROTOCOL.recent"). Client code is advised to not change these settings.

        Parameters:
        item - The item to add
        maxInList - The maximum number of items in the list
      • setRecent

        public void setRecent​(Item itemType,
                              BasicItem item,
                              int maxInList)
        Add an item to the "recently used items" list. Each type of item has their own list which may contain at most maxInList items.

        Note! The lists are stored as string of colon-separated ID:s in the setting given by the item type. For example the recently used protocols are found in the setting: getSetting("PROTOCOL.recent"). Client code is advised to not change these settings.

        Parameters:
        itemType - The type of item
        item - The item to add (or null to add a 'none' entry)
        maxInList - The maximum number of items in the list
      • setRecent

        public void setRecent​(Item itemType,
                              BasicItem item,
                              ItemSubtype subtype,
                              int maxInList)
        Add an item to the "recently used items" list when used for a specific item subtype. Each type of item+subtype has their own list which may contain at most maxInList items.

        Note! The lists are stored as string of colon-separated ID:s in the setting given by the item type. For example the recently used protocols are found in the setting: getSetting("PROTOCOL.#subtype-id.recent"). Client code is advised to not change these settings.

        Parameters:
        itemType - The type of item
        item - The item to add (or null to add a 'none' entry)
        subtype - The subtype of the parent item (can be null)
        maxInList - The maximum number of items in the list
        Since:
        3.15
      • setRecent

        public void setRecent​(Item itemType,
                              BasicItem item,
                              String subList,
                              int maxInList)
        Add an item to the "recently used items" list. Each type of item has their own list and sublists which may contain at most maxInList items.

        Note! The lists are stored as string of colon-separated ID:s in the setting given by the item type and sublist name. For example the recently used protocols are found in the setting: getSetting("PROTOCOL.subList.recent"). Client code is advised to not change these settings.

        Parameters:
        itemType - The type of item
        item - The item to add (or null to add a 'none' entry)
        subList - The sublist
        maxInList - The maximum number of items in the list
        Since:
        3.15
      • setRecent

        public void setRecent​(String key,
                              String value,
                              int maxInList)
        Add a value to the list of recently used values for the specified key. Each key has it's own list of values which may contain at most maxInList values. If the value is already in the list it is moved to the front of the list.

        Note! The lists are stored as string of colon-separated ID:s in the setting given by the key. For example, if key is "RAWDATATYPE", the recently used values are found in the setting: getSetting("RAWDATATYPE.recent"). Client code is advised to not change these settings.

        Parameters:
        key - The key to the list
        value - The value to add
        maxInList - The maximum number of values in the list
      • getNumRecent

        public int getNumRecent​(Item itemType)
        Get the number of recently used items in the list.
        Parameters:
        itemType - The type of items
      • getNumRecent

        public int getNumRecent​(Item itemType,
                                ItemSubtype subtype)
        Get the number of recently used items in the list.
        Parameters:
        itemType - The type of items
        subtype - The subtype of the parent item (can be null)
        Since:
        3.0
      • getNumRecent

        public int getNumRecent​(Item itemType,
                                String subList)
        Get the number of recently used items in a list with a sublist.
        Parameters:
        itemType - The type of items
        subList - The name of the sublist
        Since:
        2.5
      • getNumRecent

        public int getNumRecent​(String key)
        Get the number of recently used value in the list.
        Parameters:
        key - The key to the list
      • getRecent

        public <T extends BasicItemList<T> getRecent​(DbControl dc,
                                                       Item itemType)
        Get all recently used items of the specified type. The list only contains items that the logged in user has read permission to and that hasn't been deleted. Thus, the getNumRecent(Item) may return a larger number than what is actually returned in this list.
        Parameters:
        dc - The DbControl used to access the database
        itemType - The type of items
        Returns:
        A list with the items (may contain null entries)
      • getRecent

        public <T extends BasicItemList<T> getRecent​(DbControl dc,
                                                       Item itemType,
                                                       ItemSubtype subtype)
        Get all recently used items of the specified type. The list only contains items that the logged in user has read permission to and that hasn't been deleted. Thus, the getNumRecent(Item, ItemSubtype) may return a larger number than what is actually returned in this list.
        Parameters:
        dc - The DbControl used to access the database
        itemType - The type of items
        subtype - The subtype of the parent item (can be null)
        Returns:
        A list with the items (may contain null entries)
        Since:
        3.0
      • getRecent

        public <T extends BasicItemList<T> getRecent​(DbControl dc,
                                                       Item itemType,
                                                       String subList)
        Get all recently used items of the specified type in a given sublist. The list only contains items that the logged in user has read permission to and that hasn't been deleted. Thus, the getNumRecent(Item) may return a larger number than what is actually returned in this list.
        Parameters:
        dc - The DbControl used to access the database
        itemType - The type of items
        subList - The name of the sublist
        Returns:
        A list with the items (may contain null entries)
        Since:
        2.5
      • getRecent

        public List<String> getRecent​(String key)
        Get all recently used values for the specified key. Changes to the list are not recorded in the database. Use setRecent(String, String, int) instead.
        Parameters:
        key - The key to the list
        Returns:
        A list containing the values or an empty list if no recently used value has been stored
      • getRecent

        public String getRecent​(String key,
                                int index)
      • clearRecent

        public void clearRecent​(Item itemType)
        Clear the recently used items list from items of the specified type.
        Parameters:
        itemType - The type of items
      • clearRecent

        public void clearRecent​(Item itemType,
                                ItemSubtype subtype)
        Clear the recently used items list from items of the specified type.
        Parameters:
        itemType - The type of items
        subtype - The subtype of the parent item (can be null)
        Since:
        3.0
      • clearRecent

        public void clearRecent​(Item itemType,
                                String subList)
        Clear the recently used items sublist from items of the specified type.
        Parameters:
        itemType - The type of items
        subList - The name of the sublist
      • clearRecent

        public void clearRecent​(String key)
        Clear the recently used values list.
        Parameters:
        key - The key to the list
      • clearAllRecent

        public void clearAllRecent()
        Clear all recently used values lists.
      • getRecentSettingName

        private String getRecentSettingName​(String key)
      • getSetting

        public String getSetting​(String name)
        Get a value.
        Parameters:
        name - The name of the value
        Returns:
        The current value or null if no value exists
        See Also:
        setSetting(String, String)
      • setSetting

        public String setSetting​(String name,
                                 String value)
        Set a value. This property is stored in the database.
        Parameters:
        name - The name of the value
        value - The value
        Returns:
        The old value or null if no old value existed.
        See Also:
        getSetting(String)
      • removeSetting

        public String removeSetting​(String name)
        Remove a value.
        Parameters:
        name - The name of the value
        Returns:
        The old value or null if no old value existed.
      • getObject

        public <T> T getObject​(String name)
        Get an object.
        Parameters:
        name - The name of the value
        Returns:
        The current value or null if no value exists
        See Also:
        setObject(String, Object)
      • setObject

        public <T> T setObject​(String name,
                               Object value)
        Set a value. This property is not stored in the database.
        Parameters:
        name - The name of the value
        value - The value
        Returns:
        The old value or null if no old value existed.
        See Also:
        getObject(String)
      • removeObject

        public <T> T removeObject​(String name)
        Remove a value.
        Parameters:
        name - The name of the value
        Returns:
        The old value or null if no old value existed.
      • copyObjectsAndTemporaryFilters

        public void copyObjectsAndTemporaryFilters​(ItemContext other)
        Copies all objects and temporary filters from this context to another context.
        Since:
        3.6
      • getQuery

        public <T extends Query> T getQuery()
      • setQuery

        public void setQuery​(Query query)
      • configureQuery

        public void configureQuery​(DbControl dc,
                                   EntityQuery query,
                                   boolean autoLeftJoin)
                            throws BaseException
        Use the settings in this context to configure a query.
        Parameters:
        dc - The DbControl that will be used to execute the query
        query - The query to configure
        autoLeftJoin - If true, and the sort property and filters are checked for associations to other items, which are automatically left joined to the query (instead of the hibernate default of inner join) (this feature is experimental)
        Throws:
        BaseException - If configuring the query fails.
        Since:
        2.8
      • copyFrom

        void copyFrom​(ItemContext other,
                      boolean forceAll)
        Copy settings from another context to this context. Only settings which doesn't have been set in this context is copied from the other context, unless the forceAll parameter is set.
      • filterOnSelectedItems

        public void filterOnSelectedItems​(EntityQuery query)
        Add a filter to the given query that restricts it to only return items that have been selected. If no items have been selected the query is not modified.
        Parameters:
        query - The query to filter
        Since:
        2.17