<p>about your learning experience to help us improve.</p>

You've completed

cleanFiles/bookmap_SAP_Commerce_Cloud_Essentials_for_Develope_en-US_learning-sap-com_lsc-prod.zip (MMCP-DROPZONE) - 2024-11-21T07:42:21.000Z

Implementing Flexible Search APIs

<div id="content"><p tabindex="0">You can invoke the Flexible Search APIs to find SAP Commerce Items in your code. These APIs are methods of the FlexibleSearchService Spring bean.</p><p tabindex="0">Watch the following video to learn more about these flexible search APIs.&nbsp;</p><div class="kalturaVideoLessonWrapper"><div aria-label="This video will guide you through flexible search APIs." class="kalturaVideoLessonContainer" data-testid="video" id="1_oo3spe3b"></div></div></div>

Flexible Search APIs

Exploring the Technical Essentials of SAP Commerce Cloud

Using Flexible Search APIs

When we execute Flexible Search queries from code, via an API, such as the methods of FlexibleSearchService, it almost always makes much more sense to obtain a java.util.List of model objects  of a specific type, instead of querying for arbitrary attributes, like we would in the HAC Flexible Search Console. To obtain “whole model objects”, we first query for just the PKs, all of a single commerce type (NOTE: the PKs don’t necessarily have to come from an attribute named PK). We pass the query – here via a Java String – into the constructor of a new FlexibleSearchQuery object. This “primes” the object for query reuse. From this point forward, we work with the FlexibleSearchQuery object and not the String. Execute this query by passing the FlexibleSearchQuery object into the search() method of FlexibleSearchService to yield a servicelayer SearchResult. The use of the Java Generic – here, using a fictitious CarModel class – alters the return type of the result object’s getResult() method, such that it returns a List. If you prefer, you can combine the last three statements into a single line of code that looks like this. In most situations, you don’t have to worry about JOINs when working with the APIs. Instead, once you obtain your List of model objects, you can easily “navigate” or “traverse” to any linked objects needed by simply executing a few extra lines of code. Also, make SURE your IDE correctly chooses the import for de.hybris.platform.servicelayer.search.SearchResult , and not de.hybris.platform.jalo.SearchResult. servicelayer, not jalo Otherwise, you will waste a lot of time trying to get the SearchResult object returned by FlexibleSearchService.search() to “convert” or “cast” to a variable of the wrong kind of SearchResult. Lastly, some context… The methods we are showing in our examples are all just like arbitrary DAO (Data Access Object) implementation methods you would write to encapsulate your Flexible Search operations for other members of your team. They have programmer-friendly names, they generally return java.util.Lists of Java Model objects corresponding to Commerce types, and they’re often parameterized, as we’ll see in the upcoming slides. Let’s take a typical DAO method, and add parameters – ones that map to Commerce Atomic types, first. It’s very simple, if you look at it right. Every atomic type in Commerce, corresponds to and converts to a Java backing class, generally of the identical name. For example, java.lang.Integer, java.lang.String, or java.util.Date. So… if your DAO method uses parameters of these types, they can be applied seamlessly to Flexible Search queries with placeholders. (Note: placeholders are only available when using the API, and not via HAC Flexible Search Console) Placeholders within the query String are arbitrary names prefixed with a question mark Once you have instantiated and “primed” the FlexibleSearchQuery object, you invoke addQueryParameter() once for each placeholder name (even if the same placeholder name appears multiple times in the query). And the rest is the same as before.  When using NON-atomic parameters, i.e., parameters expecting references, it’s just as easy, as long as you think about it the right way. Everything is the same as before, except that you now have to take the Java conversion concept one step further. Remember – from the Data Modeling lesson – that when you declare any Commerce type with generate=“true”, the build process will generate a corresponding Java class to go with the Commerce type. So here, the DAO method takes a parameter of type EmployeeModel in the Java domain, which maps to the Employee type in the Commerce domain. The only thing that’s confusing – at first – is that you need to remember that the Flexible Search query String is written for the Commerce domain. So in this example, the WHERE-clause predicate’s placeholder seems to want a PK value, which does make sense. Think differently – instead, think of the placeholder as wanting a Commerce Reference of type Employee (because Car’s ‘employee’ attribute is declared to be of type Employee, borrowing this example from earlier lessons). And – here’s the key to understanding the semantics a reference of type Employee in the Commerce domain maps perfectly to a reference of the corresponding type EmployeeModel in the Java domain. Get it? Therefore, you pass, to the fsq.addQueryParameter() method, a Java EmployeeModel reference which gets converted to an Employee reference when binding to the placeholder in the query String, because the query String is in the Commerce domain. (In the Commerce domain, “references” are, of course, implemented via PKs, but the semantics are the important part to this API). NOTE:  Some newer versions of the API allow you to pass-in a PK, instead. But older versions do NOT, because technically, a PK is an instance of a Commerce atomic type, backed by the PK class, which is not castable to/from, say, an EmployeeModel class, thus you’d get a ClassCastException. Now, in the rare case that you DO want to query for a single, specific attribute, (other than one that returns PKs), here’s how it’s done. It’s not that bad, and it’s usually used to return the result of a group function, like count(), sum(), avg(), min(), or max(). It simply requires that you “map” the result-column types to the corresponding Java types. fsq.setResultClassList() wants a java.util.List of Java class references, even if there’s only one type to be mapped. For convenience and compactness, this example uses (what I call) “array literal” notation to create a one-element array (because this can be done on a single line of code), then, the example uses the static Arrays.asList() utility method to build a List from the array (also via a single line of code). This approach avoids a lot of code clutter. The Java generic used in this situation is simply the mapped type, which the result.getResult() method happily returns a java.util.List of. Not too bad. BTW, in case you're unfamiliar with car-speak, VIN stands for Vehicle Identification Number – every individual car manufactured must have a unique, VIN stamped into it. Querying for two or more individual attributes is fairly inconvenient. We mainly show it here to a) demonstrate that it actually can be done, and b) to convince you why this approach is generally undesirable So, as with the previous example, we need to map the result types, positionally (this time with two array elements, which produces a List of two types. So far, so good But this time, our result comes back as a List of List of Object, and you aren’t allowed to be more specific. The ”inner” List represents a single “result row”, where each element of that list is one result column of that result row and the “outer” List is the collection of result rows. It’s all of the downcasting that makes this approach messy, but it is possible and it may be useful in situations where you have no idea, ahead of time, what the structure of the result will be. But generally, it’s not very convenient. In the Commerce domain, the java.util.Date atomic type, of course maps to / converts to the Java class of the same name. So that part is easy. Obtaining a system timestamp (i.e., date/time) is also easy. But manipulating dates in Java can be tricky, if you are to avoid using the deprecated methods of Java’s java.util.Date class, which, for decades now, is only meant to hold timestamps that are not meant to change. In other words, instances of Java’s java.util.Date class are not to be used for manipulating date/time values. To do it properly, we instead obtain an instance of GregorianCalendar via the factory method Calendar.getInstance() This method returns an instance initialized to current system date/time. Next (and the main reason for having to manipulate dates), in order to have a so-called “date only” object, we must zero-out the time fields. The Calendar class has some generic methods for doing just that. They look quite odd, taking a field constant and a value. This is because the Calendar (abstract class) was designed to be able to be subclassed by various kinds of calendars: GregorianCalendar (which comes OOTB), Julian calendar, Lunar calendar, I’ve even seen an implementation of Martian calendar used at the JPL (Jet Propulsion Laboratory). The tricky part here, once you understand the way field constants work, is to remember to zero-out the millisecond field – this is really easy to forget. Failing to do so, will make it very unlikely that two date-only objects from the same date will be equal after you only zero-out hours, minutes, and seconds, and it will drive you crazy. Once all of your Calendar object’s time fields are zeroed-out you then obtain a java.util.Date object from it via the getTime() method. I know – a method called getTime() that returns a Date instance. Well, as I already said, java.util.Date is meant for timestamps, so I guess that makes sense. Apply this java.util.Date object (in the Java domain) to the Flexible Search placeholder, which expects a java.util.Date primitive in the Commerce domain, and the rest is the same as before. Conceptually speaking, Pagination is a feature (usually taken-care-of by a database) that makes it easy and efficient for a web application to display a large number of query results, one “page” at a time. An obvious example of this is the Results tab of HAC’s Flexible Search console, which allows you to show all results at once, or show them in pages of 10, 25, 50, or 100 results per page. Not only is pagination optimized for obtaining the first page-worth of results super-fast, (regardless whether the total number of results is one thousand or one million), but the same Query Result item (cached in the commerce domain) is reused the whole time the user flips through the pages. This means that it’s super-efficient, since the original query does not need to be re-processed for each page. Pagination mechanisms may also pre-fetch the next page-worth of items, improving the perceived quickness of data retrieval. The problem with handling pagination via the underlying database is that there is no standard SQL syntax for pagination. For example, DB2 SQL syntax uses keywords LIMIT and OFFSET, Oracle SQL syntax uses the keyword TOP n, Etc. To get around the underlying-database syntax inconsistencies, AND to make best use of the Commerce cache, the Flexible Search API can, instead, handle Pagination programmatically. First, write your query using NO pagination SQL syntax. Then, we let the API handle pagination as follows: invoke the query object’s setNeedTotal(true), (when “displaying results 11 through 20 of 345” – the “345” is the total we need.) Then, you invoke the query object’s setCount() method to specify the number of results to retrieve for a single page, and invoke the query object’s setStart() method to indicate which specific result is the first one on your page. (results start at #0). Finally, invoke FlexibleSearchService’s search() method, passing in the FlexibleSearchQuery object. Later, when displaying another “page” worth of results, change the ‘start’ number via setStart(), and as long as you instantiate the FlexibleSearchQuery (in the Java domain) with the identical query string, even though it’s a new Java instance, FlexibleSearchService will reuse the same, SearchResult item from the Commerce cache. Note: This sample code, shows reuse of the FlexibleSearchQuery object (perhaps attached to the user session). The same FlexibleSearchQuery object     Is repeatedly passed (along with the desired page number) to a DAO method. This example method calculates the start item from page number and page size. When the Commerce build process generates the Java model classes, not only do they have a getter and setter method for each of the commerce type’s attributes, but there is also a String constant (i.e., public static final) for each declared attribute name and one for the commerce type’s code (i.e., its declared name). These can be used to rewrite the Flexible Search query String in terms of these constants, instead of including the names explicitly. While this hurts readability slightly, it makes it impossible to have a spelling error in the typename or attribute name without getting an immediate error in your Java editor (or during compilation) you don’t have to wait until the query is invoked to find out. Alternately, this also allows you to take advantage of your Java editor’s auto-complete feature.

Share feedback

Follow guided learning and develop the skills you need at your own pace

Join a moderated learning group to engage with our experts and peers

Find the right learning resources to drive your career as a developer

Sign up to access exclusive student learning journeys

Discover the SAP product knowledge you need to help you progress in your career

Develop your skills

Learn.png

Want to learn more about the value of learning with SAP?

View available SAP Certifications on SAP Learning 

Purchase a subscription and book your exam

Validate your SAP expertise

SAP Certification validates your skills, sets you apart from the crowd, and demonstrates you have the knowledge you need to succeed.

Certify.png

Accelerate your career 

Upskill in key innovation topics through openSAP's free, expert-led online courses, microlearning, and podcasts.

Join SAP Community and connect with a global network of experts and peers to ask and answer questions.

Search for SAP product documentation or browse all SAP Learning Journeys to become competent in the SAP solutions you need.

Log in to SAP Learning Hub and access the entire SAP Learning portfolio, live practice systems, and social learning opportunities.

Find free tutorials, trials, downloads, and technical product information in the SAP Developer Center.

Book live classes (online and in person) and purchase SAP Certification and SAP Learning Hub subscriptions.