chore: restructure examples (#22)

Co-authored-by: Simon Jingzhe Huang <[email protected]>

Author: Simon-Wong-hjz

.github/workflows/run-examples.yaml

@@ -57,6 +57,7 @@ jobs:
         working-directory: sdk-repo/examples
         run: |
           mvn install exec:java \
+            -Dexec.mainClass="com.expediagroup.sdk.xap.examples.XapSdkDemoTestRun" \
             -Dcom.expediagroup.xapjavasdk.apikey="${{ secrets.API_KEY }}" \
             -Dcom.expediagroup.xapjavasdk.apisecret="${{ secrets.API_SECRET }}" \
             -Dcom.expediagroup.xapjavasdk.vrbokey="${{ secrets.VRBO_KEY }}" \

examples/README.md

@@ -12,14 +12,19 @@ Currently, the following scenarios are included:
 
 ### Lodging
 
-#### Shopping
+- [`ListingsQuickStartScenario.java`](src/main/java/com/expediagroup/sdk/xap/examples/scenarios/lodging/ListingsQuickStartScenario.java):
 
-##### Listings
+  This example demonstrates how to search for properties with a location keyword with filters
+  applied in Lodging Listings API.
+
+- [`QuotesQuickStartScenario.java`](src/main/java/com/expediagroup/sdk/xap/examples/scenarios/lodging/QuotesQuickStartScenario.java):
+
+  This example demonstrates how to search for property quotes with property IDs in Lodging Quotes API.
 
 - [
-  `QuickStartExample.java`](src/main/java/com/expediagroup/sdk/xap/examples/scenarios/lodging/shopping/listings/QuickStartExample.java):
-  This example demonstrates how to search for properties with a location keyword with filters
-  applied.
+  `AvailabilityCalendarsQuickStartScenario.java`](src/main/java/com/expediagroup/sdk/xap/examples/scenarios/lodging/AvailabilityCalendarsQuickStartScenario.java):
+
+  This example demonstrates how to search for availability calendars with property IDs in Lodging Availability Calendar API.
 
 We are continuously adding more scenarios to demonstrate the usage of other XAP APIs.
 
@@ -35,16 +40,44 @@ We are continuously adding more scenarios to demonstrate the usage of other XAP
 
 1. Clone the repository.
 2. Navigate to the project directory `examples`.
-3. Set your API key and secret in the environment variables `XAP_API_KEY` and `XAP_API_PASSWORD`.
-   > **Note:** You can also replace the value of `xapApiKey` and `xapApiPassword` in the
-   > [`Constants.java`](src/main/java/com/expediagroup/sdk/xap/examples/Constants.java) file, but we
-   > recommend using environment variables out of security concerns.
-4. Run `mvn clean install` to build the project and install the dependencies including the XAP SDK.
+3. Run `mvn clean install` to build the project and install the dependencies including the XAP SDK.
 
 ## Running the Examples
 
-To run the examples, simply navigate to the example class you want to run and execute the `main`
-method.
+### Run with IntelliJ IDEA
+1. Navigate to the example class you want to run
+2. Right-click on the class name and select `More Run/Debug` -> `Modify Run Configuration`
+3. Check the `Modify options` -> `Add VM options` and add the following VM options:
+    ```
+    -Dcom.expediagroup.xapjavasdk.apikey="{API_KEY}"
+    -Dcom.expediagroup.xapjavasdk.apisecret="{API_SECRET}"
+    ```
+    Replace `{API_KEY}` and `{API_SECRET}` with your actual API key and secret.
+    > **Note:** If you are running the examples for Vrbo, you would need the following VM options instead:
+    > ```
+    > -Dcom.expediagroup.xapjavasdk.vrbokey="{VRBO_KEY}"
+    > -Dcom.expediagroup.xapjavasdk.vrbosecret="{VRBO_SECRET}"
+    > ```
+    > The key you use must be enabled for Vrbo brand. If you are not sure, please reach out to your account manager.
+4. Click `OK` and then run the `main` method of the example class.
+
+### Run with Command Line
+Run the following command to run the example class you want to run:
+```
+mvn exec:java -Dexec.mainClass="path.to.example.ExampleClassName" \
+    -Dcom.expediagroup.xapjavasdk.apikey="{API_KEY}" \
+    -Dcom.expediagroup.xapjavasdk.apisecret="{API_SECRET}"
+```
+Replace `path.to.example.ExampleClassName` with the full path to the example class you want to run,
+and `{API_KEY}` and `{API_SECRET}` with your actual API key and secret.
+
+> **Note:** If you are running the examples for Vrbo, you should use the following command instead:
+> ```
+> mvn exec:java -Dexec.mainClass="path.to.example.ExampleClassName" \
+>     -Dcom.expediagroup.xapjavasdk.vrbokey="{VRBO_KEY}" \
+>     -Dcom.expediagroup.xapjavasdk.vrbosecret="{VRBO_SECRET}"
+> ```
+> The key you use must be enabled for Vrbo brand. If you are not sure, please reach out to your account manager.
 
 ## License
 

examples/pom.xml

@@ -31,7 +31,7 @@
         <maven.compiler.source>1.8</maven.compiler.source>
         <maven.compiler.target>1.8</maven.compiler.target>
         <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
-        <xap-java-sdk.sdk.version>0.0.8-SNAPSHOT</xap-java-sdk.sdk.version>
+        <xap-java-sdk.sdk.version>0.0.15-SNAPSHOT</xap-java-sdk.sdk.version>
     </properties>
 
     <repositories>
@@ -86,14 +86,6 @@
                     </execution>
                 </executions>
             </plugin>
-            <plugin>
-                <groupId>org.codehaus.mojo</groupId>
-                <artifactId>exec-maven-plugin</artifactId>
-                <version>3.3.0</version>
-                <configuration>
-                    <mainClass>com.expediagroup.sdk.xap.examples.XapSdkDemoApplication</mainClass>
-                </configuration>
-            </plugin>
         </plugins>
     </build>
 </project>

examples/src/main/java/com/expediagroup/sdk/xap/examples/XapSdkDemoApplication.java

@@ -0,0 +1,55 @@
+/*
+ * Copyright (C) 2024 Expedia, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.expediagroup.sdk.xap.examples;
+
+import com.expediagroup.sdk.xap.examples.scenarios.lodging.AvailabilityCalendarsQuickStartScenario;
+import com.expediagroup.sdk.xap.examples.scenarios.lodging.ListingsQuickStartScenario;
+import com.expediagroup.sdk.xap.examples.scenarios.lodging.QuotesQuickStartScenario;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+/**
+ * This is an aggregation runner for all the scenarios for test purposes.
+ * For reference, see the individual scenarios in the scenarios package.
+ */
+public class XapSdkDemoTestRun {
+  private static final Logger logger = LoggerFactory.getLogger(XapSdkDemoTestRun.class);
+
+  /**
+   * Main method.
+   */
+  public static void main(String[] args) {
+
+    logger.info(
+        "============================== Running Lodging Scenarios =============================");
+
+    AvailabilityCalendarsQuickStartScenario availabilityCalendarsQuickStartScenario =
+        new AvailabilityCalendarsQuickStartScenario();
+    availabilityCalendarsQuickStartScenario.run();
+
+    ListingsQuickStartScenario listingsQuickStartScenario = new ListingsQuickStartScenario();
+    listingsQuickStartScenario.run();
+
+    QuotesQuickStartScenario quotesQuickStartScenario = new QuotesQuickStartScenario();
+    quotesQuickStartScenario.run();
+
+    logger.info(
+        "=============================== End of Lodging Scenarios ==============================");
+
+    System.exit(0);
+  }
+}

examples/src/main/java/com/expediagroup/sdk/xap/examples/XapSdkDemoTestRun.java

@@ -16,9 +16,29 @@
 
 package com.expediagroup.sdk.xap.examples.scenarios;
 
+import com.expediagroup.sdk.xap.client.XapClient;
+
 /**
  * Interface for scenarios.
  */
 public interface XapScenario {
+
+  String PARTNER_TRANSACTION_ID = "xap-java-sdk-examples";
+
   void run();
+
+  /**
+   * Create a client.
+   *
+   * @return XapClient
+   */
+  default XapClient createClient() {
+    String key = System.getProperty("com.expediagroup.xapjavasdk.apikey");
+    String secret = System.getProperty("com.expediagroup.xapjavasdk.apisecret");
+    return XapClient
+        .builder()
+        .key(key)
+        .secret(secret)
+        .build();
+  }
 }

examples/src/main/java/com/expediagroup/sdk/xap/examples/scenarios/XapScenario.java

@@ -0,0 +1,107 @@
+/*
+ * Copyright (C) 2024 Expedia, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.expediagroup.sdk.xap.examples.scenarios.lodging;
+
+import com.expediagroup.sdk.xap.client.XapClient;
+import com.expediagroup.sdk.xap.models.AvailabilityCalendarResponse;
+import com.expediagroup.sdk.xap.operations.GetLodgingAvailabilityCalendarsOperation;
+import com.expediagroup.sdk.xap.operations.GetLodgingAvailabilityCalendarsOperationParams;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import java.util.Arrays;
+import java.util.HashSet;
+
+/**
+ * This example demonstrates how to use Availability Calendar api with simple search.
+ * Note: this is a Vrbo scenario. You need a key that is enabled for Vrbo brand to run this.
+ */
+public class AvailabilityCalendarsQuickStartScenario implements VrboScenario {
+
+  private static final Logger LOGGER =
+      LoggerFactory.getLogger(AvailabilityCalendarsQuickStartScenario.class);
+
+  public static void main(String[] args) {
+    new AvailabilityCalendarsQuickStartScenario().run();
+    System.exit(0);
+  }
+
+  @Override
+  public void run() {
+    // This example returns the availability of each day for a range of dates for given Expedia
+    // lodging properties.
+
+    LOGGER.info(
+        "=================== Running AvailabilityCalendarsQuickStartScenario ===================");
+
+    LOGGER.info(
+        "================= Executing GetLodgingAvailabilityCalendars Operation ================");
+
+
+    // Build the query parameters with GetLodgingAvailabilityCalendarsOperationParams
+    GetLodgingAvailabilityCalendarsOperationParams availabilityCalendarsOperationParams =
+        GetLodgingAvailabilityCalendarsOperationParams.builder()
+            .partnerTransactionId(PARTNER_TRANSACTION_ID)
+            // Set of Expedia Property IDs.
+            .propertyIds(new HashSet<>(Arrays.asList("87704892", "12410858")))
+            .build();
+
+    XapClient xapClient = createClient();
+
+    // Execute the operation and get the AvailabilityCalendarsResponse
+    AvailabilityCalendarResponse availabilityCalendarResponse =
+        xapClient.execute(new GetLodgingAvailabilityCalendarsOperation(
+          availabilityCalendarsOperationParams)).getData();
+
+    // If you want to use the async method, you can use the following code:
+    // ---------------------------------------------------------------
+    // CompletableFuture<Response<AvailabilityCalendarResponse>> completableFuture =
+    //   xapClient.executeAsync(
+    //     new GetLodgingAvailabilityCalendarsOperation(availabilityCalendarsOperationParams));
+    // completableFuture.thenAccept(availCalendarResponse -> {
+    //   // Your code here
+    // });
+    // ---------------------------------------------------------------
+
+    LOGGER.info(
+        "================== GetLodgingAvailabilityCalendarsOperation Executed =================");
+
+    if (availabilityCalendarResponse == null
+        || availabilityCalendarResponse.getAvailabilityCalendars() == null
+        || availabilityCalendarResponse.getAvailabilityCalendars().isEmpty()) {
+      throw new IllegalStateException("No properties found.");
+    }
+
+    // The AvailabilityCalendarsResponse contains a transaction ID for troubleshooting
+    LOGGER.info("Transaction ID: {}", availabilityCalendarResponse.getTransactionId());
+
+    // To access the properties, iterate through the list of properties
+    availabilityCalendarResponse.getAvailabilityCalendars().forEach(availCalendar -> {
+      LOGGER.info("========== Property:{} Start ==========", availCalendar.getPropertyId());
+
+      // Availability of property: A string of codes that shows property availability, one for every
+      // day in the specified date range.
+      // Valid values include Y (available) and N (unavailable).
+      LOGGER.info("Availability: {}", availCalendar.getAvailability());
+
+      LOGGER.info(
+          "==================================== Property End ===================================");
+
+      LOGGER.info(
+          "===================== End AvailabilityCalendarsQuickStartScenario ====================");
+    });
+  }
+}