/*
* 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 openbook.server;
import java.util.List;
import java.util.Map;
import javax.persistence.EntityManagerFactory;
import openbook.domain.Book;
import openbook.domain.Customer;
import openbook.domain.Inventory;
import openbook.domain.PurchaseOrder;
import openbook.domain.ShoppingCart;
/**
* A simple service to select Books, purchase them and manage their inventory.
* A service handle can be obtained from {@link ServiceFactory#getService(String)
* Service Factory}.
*
* @author Pinaki Poddar
*
*/
public interface OpenBookService {
public static final String DEFAULT_UNIT_NAME = "OpenBooks";
/**
* Starts a session for the given named Customer.
* If no record of the given name exists, a new Customer record is created.
*
* @param name name of a possibly existing customer. Or a new one.
*
* @return a Customer
*/
public Customer login(String name);
/**
* Selects a list of Books matching the given conditions.
* Each of the conditional parameter can be null.
* A null parameter implies that the resultant query should ignore that parameter.
*
* @param title title of the Book
* @param min minimum price
* @param max maximum price
* @param author name of author
* @param decorators to modify the executable query such as its range.
*/
public List<Book> select(String title,
Double min, Double max,
String author,
QueryDecorator...decorators);
/**
* Gets the query String for the given parameters.
* Each of the conditional parameter can be null.
* A null parameter implies that the resultant query should ignore that parameter.
*
* @param title title of the Book
* @param min minimum price
* @param max maximum price
* @param author name of author
* @param decorators to modify the executable query such as its range.
*/
public String getQuery(String title,
Double min, Double max,
String author);
/**
* Runs an arbitrary JPQL query to return a list of result.
*
* @param jpql a valid JPQL query string.
* @param resultClass type of the result.
* @param decorators zero or more QueryDecorators to be applied before Query is executed.
* @return the selected instances.
*/
<T> List<T> query(String jpql, Class<T> resultClass, QueryDecorator...decorators);
<T> List<T> getExtent(Class<T> entity);
/**
* Buys the content of the given cart.
*
* @param cart a non-empty cart.
* @return a PurchaseOrder for the content of the cart.
*/
public PurchaseOrder placeOrder(ShoppingCart cart);
/**
* Delivers the given order. Delivery changes the status of the order, decrements
* inventory and finally removes the line items.
*
* @param order a PENDING order to be delivered.
* @return the PurchaseOrder after delivery.
*
*/
public PurchaseOrder deliver(PurchaseOrder order);
/**
* Add inventory of the given Book by the given quantity.
*
* @param b a Book whose inventory is to be incremented
* @param quantity positive number.
*
* @return the Book after incrementing its inventory.
*/
public Book supply(Book b, int quantity);
/**
* Gets the list of orders of given status.
*
* @param status status of the orders. null implies all orders.
*
* @return list of orders sorted by their placement dates.
*/
public List<PurchaseOrder> getOrders(PurchaseOrder.Status status, Customer customer);
/**
* Gets the list of Books whose inventory is lower than the given limit.
*
* @param limit reorder limit. null implies all inventory.
*
* @return list of Books with inventory lower than the given limit.
*/
public List<Inventory> getReorderableBooks(int limit);
/**
* Count the number of instances of the given persistent type.
*
* @param cls a persistent type.
* @return number of persistent entity of the given type.
*/
public long count(Class<?> cls);
/**
* Populates the underlying data repository with sample values, only if
* the data repository is empty.
*
* @param loadParameters control the number of Books etc. to be created.
* null is allowed.
*
* @return true if the repository is initialized by this invocation.
*/
public boolean initialize(Map<String,Object> loadParameters);
/**
* Cleans everything. Be careful.
*/
public void clean();
/**
* Gets the underlying persistence unit.
*
*/
public EntityManagerFactory getUnit();
/**
* Gets the name of the underlying persistence unit.
*
*/
public String getUnitName();
/**
* Affirms if the transaction on this persistence unit is managed by a container.
*
*/
public boolean isManaged();
}