Category:Subset

From JRapid

JRapid defines the Subset element for restricting the results shown by Listings, Filters or Properties of type "entity" (see subset(attribute)).

It can be understood also by comparing it to SQL languages or Relational Algebra:

• Conditions that filter the list of instances (selection)
• Specification of properties to be shown (projection)

Subsets selects the displayed instances using conditions and restrictions. Conditions operate between properties values and restrictions spcecifies more advanced expressions like HQL queries. Both conditions and restrictions can be grouped using the or and and tags to get extra restriction logic.

Each subset will provide an associated web service method that will return only the specified instances showing specified properties (see example below).

Spec:

<subset 
       name = NAME
       displayproperties = COMA_SEPARATED_PROPERTIES
       order = ORDER
       (restrict?, (param|condition|and|or|restriction)*) 
/>

How to add a Subset:

As said above, subsets restrict results shown by listings. A listing without a subset will return all the instances of the listing. A listing which specifies a subset can return all, none or some instances of the entity. In other words, a listing which specifies a subset returns only the instances which meets the specifies conditions and/or restrictions of the subset.

To add a subset to a listing you should first create the subset by either writing the xml code inside the entity element or using the IDE.

Go to the entity where you will create a listing and click the (+) button > Add Subset:

The Editing Subset window will be opened.

When submitting the window, the corresponding xml code will be appended to the app xml.

Finally, you should create a listing in the same entity where you created the subset and specify that the listing will use that subset. This is done in the "subset" combobox in the Editing Listing window.

Example:

• Subsets in Listings:

The following image displays a listing for a Company entity. This listing is the default-autogenerated listing which do not specify any subset so it always shows all the company instances stored in the database.

In a typical CRM application (Customer Relationship Management) a common use case is to list for each seller of the company a listing of the companies where he is the responsible or the companies in which he has an opportunity.

The first step for creating this restricted listing of companies is to create a subset in the Company entity. This subset will specify a condition which will operate with the "responsible" property of the Company entity and match it to a "seller" parameter and will specify also a restriction which will query if the seller parameter has an opportunity in that company (me).

To define both a condition and restriction in a subset you should change the subset's mode to "mixed".

<entity label="Company" name="Company">
  ...
  <property name="responsible" label="Responsible" entity="Seller"/> 
  ...
  <subset name="forSeller">
       <param entity="Seller" name="seller"/>
       <or>
          <condition field="responsible" value="seller"/>
          <restriction expr="exists (select opp from Opportunity as opp where
                     opp.company.id=me.id and opp.seller.id=?)">
              <param value="seller.id"/>
          </restriction>
       </or>
  </subset>
  ...
</entity>

Finally, you should create a listing specifying the "forSeller" subset.

<entity label="Company" name="Company">
  ...
  <property name="responsible" label="Responsible" entity="Seller"/> 
  ...
  <listing name="companiesListing" subset="forSeller"/>
  <subset name="forSeller">
       <param entity="Seller" name="seller"/>
       <or>
          <condition field="responsible" value="seller"/>
          <restriction expr="exists (select opp from Opportunity as opp where
                     opp.company.id=me.id and opp.seller.id=?)">
              <param value="seller.id"/>
          </restriction>
       </or>
  </subset>
  ...
</entity>

To get running this listing you should embed the listing in the Seller as an embeddedlisting. The steps for creating an embeddedlisting are the same for creating a listing but with the difference that you do not need to create the subset again and that you can send parameters to the listing.

<entity label="Seller" name="Seller">
        ...
        <tab label="Companies" name="companies">
            <embeddedlisting entity="Company" label="Companies" listing="companiesListing" name="companies" subset="forSeller"
            subsetparams="."/>
        </tab>
        ...
</entity>

The "." parameter is resolved as the Seller.

For further understanding of how subset's work look at the generated java serivce method in the CompanyServicesAbstract class:

public Collection<Company> findSubsetForSellerInternal(String sellerId,
			String storedFilterName, String page, String pattern, String order,
			List<Restriction> otherRestrictions, int pageSize, String hints)
			throws ELException {
		// step 1: find params
		Seller seller = Seller.DAO().findById(sellerId);

		// step 2: build param map
		FunctionMapper fm = new FunctionMapper();
		DAO<Company> dao = Company.DAO();
		java.util.Map<String, Object> map = new java.util.HashMap<String, Object>();
		ExpressionVariableResolver evr = new ExpressionVariableResolver(map);

		map.put("seller", seller);

		// step 3: build restrictions
		List<Restriction> restrictions = new ArrayList<Restriction>();
		if (otherRestrictions != null) {
			restrictions.addAll(otherRestrictions);
		}

		Collection<Restriction> rN65624 = new ArrayList<Restriction>();

		rN65624.add(dao.getFieldRestriction("me.responsable", el.evaluate(
				"${seller}", Object.class, evr, fm)));

		Object[] paramsN65630 = new Object[1];
		paramsN65630[0] = el.evaluate("${seller.id}", Object.class, evr, fm);
		rN65624
				.add(new HibernateRestriction(
						"exists (select opp from Opportunity as opp where opp.company.id=me.id and opp.seller.id=?)",
						false, paramsN65630));

		restrictions.add(dao.getOrRestriction(rN65624));

		// step 4: order
		Order orders = null;
		if (order != null) {
			int index = (order.indexOf("d") > 0) ? Integer.valueOf(order
					.substring(0, order.indexOf("d"))) : Integer.valueOf(order);
			String[] columns = new String[] { "name", "status.name", "" };
			orders = new Order(columns[index]
					+ ((order.indexOf("d") > 0) ? " desc" : ""));
		}

		// step 5: return

		return findPageRestricted(storedFilterName, page, pattern,
				restrictions, orders, pageSize, hints);

	}