Les sites de location (type https://www.pap.fr) proposent généralement des moyens rudimentaires de recherche parmi les annonces existantes. Ce projet vise à doter l’utilisateur de moyens d’indiquer ses préférences d’une manière riche, afin de lui montrer les annonces qui lui conviennent le mieux d’abord. En particulier, au lieu de filtrer de façon binaire (ex. : inclure un appartement seulement s’il fait au moins x m²), le système permettra la compensation (ex. : inclure une annonce pour un appartement très petit s’il est très bon sur les autres critères) ; et le système permettra d’inclure comme critère la distance (en transport public) à des lieux d’intérêts pour l’utilisateur tels que son lieu de travail.
Le projet existant permet de manipuler des annonces d’appartements (programmatiquement et avec des interfaces graphiques) ; d’en générer aléatoirement ; de calculer la distance d’un appartement à un lieu en métro ; de calculer la valeur subjective d’un appartement aux yeux de l’utilisateur via sa fonction de valeur…
Une fonction de valeur est une somme de fonctions de valeur partielles. Une fonction de valeur partielle indique, sur un critère (superficie, nombre de chambres…), la valeur que l’utilisateur accorde à l’appartement sur cet aspect. La valeur d’un appartement est la somme des valeurs partielles sur chaque aspect.
L’interface Java PartialValueFunction, paramétée par le type de donnée objective, représente l’association entre des données objectives et des utilités : on lui fournit une donnée objective (par exemple une couleur) et elle retourne la valeur subjective associée, entre 0 et 1. Elle étend Function<T, Double>, où T est le type de donnée objective.
La classe LinearValueFunction implémente PartialValueFunction<Double>. On lui fournit un intervalle (par exemple [10, 50]) qui définit les points renvoyant zéro et un. Si on communique un autre nombre à la fonction entre 10 et 50, elle interpole linéairement (par exemple 20 renverrait (20−10)/(50−10)=0.25).
La classe PiecewiseLinearValueFunction permet de stocker un ensemble de paires (valeur réelle, valeur réelle entre 0 et 1 compris). Une instance de cette classe permet de mesurer l’attrait pour l’utilisateur d’un aspect donné d’un appartement. La première valeur représente une description objective de la qualité d’un appartement sur un aspect donné (par exemple la taille de l’appartement), et la deuxième, entre 0 et 1, mesure l’attrait associée à cette qualité. Cette mesure est nommée la valeur subjective, ou utilité, correspondant à la valeur objective fournie. La classe permet donc d’associer à différentes valeurs objectives leur utilité. Par exemple, on pourra associer la valeur 30 (mètre carrés) à l’utilité 0.5 et la valeur 45 (mètres carrés) à l’utilité 0.7.
Un appartement a une localisation précise (stockée dans un LatLng, permettant de représenter un endroit précis sur le globe). ValueDistFunction, une implémentation de PartialValueFunction<LatLng>, calcule la valeur partielle de la localisation : l’instance reçoit des lieux d’intérêts de l’utilisateur (par défaut, le centre de Paris), calcule le max des distances entre l’appartement et tous les lieux d’intérêts, et renvoie une interpolation linéaire avec 1 pour une distance de 0, et 0 pour une distance de 10h. (Non complètement implémenté.)
Before getting into details, let’s start the app and see what it does. Clone the project on your local repository, and then open it on Eclipse. In the documentation run.adoc, you have an overview of all the executable classes. I advice you to launch all of them, and to read the documentation in order to understand how it operates, and what the main goal of the application is. Depending on the Tenant preferences, you have a different list of apartments showing up. Now that you have a small idea of the project, it is time to read the specific documentation.
-
Read the packages.adoc to learn the impletemented packages and have detailed explanation of its classes. The
valuefunctionpackage is the most important ! The whole project revolves around it. Now that you know the packages and classes, you can do the next step. -
Read the global.adoc to see the general diagrams. You will find all the images under img.
-
Open the papyrus model on Eclipse.
-
Make sure you understand the artefact behind the model. It is the key to your future iterations in UML. You need to keep it clean.
-
Observe all the diagrams in the model. They show all that has been implemented in Java. Understanding the diagrams will help you understand the java code behind.
Now you should know everything about the different packages and classes and how they interact. Next step is to understand the code !
-
Before modifying any class, it is mandatory to have a minimum level in Java. It includes :
-
Knowing the basics of Java syntax.
-
Clearly identify the differences between a package, a class, an interface and a method.
-
Understand Maven to see how the project is designed.
-
-
In the folder src, you have the code for the project : you will find the different packages and their classes. We advice you to look at it now.
Take time to go through all the packages in order to understand their classes' implementation. The javadoc view in Eclispe is your best tool to understand the code, do not hesitate to use it to understand what a class or a method does. Use as well the different documentations that you must have read by now. It is only here to help you.
-
The name of a package must start with the type of diagram he contains (CD, UCD, ID) and should look like this: "TypeOfDiagram_Description”.
The only exception is for theJavaIterationpackage as it may contain different type of diagram. -
When you create a new child such as a use case or a new class, the name of it should finish with "UC” if it is a use case, "CD” if it is for a class diagram or "I” for an interaction diagram.
-
It allows you to use the Google MAPS API to calculate the distance between two places. For example, in DistanceSubway Class, you need it.
-
Go to https://console.cloud.google.com/ and connect to your google account (You must have one).
-
On the top left, create a new project. Once it is created, click on it.
-
Go to Api and Services, and then Credentials. Click on "Create credentials, API Key".
-
You now have created a Key. Go to API Library and enable "Distance Matrix API, Geocoding API, Directions API, Maps Elevation API, Maps JavaScript API, Roads API".
-
Go back to credentials, click on the key, and restrain it to only those API.
-
Before using it, you must activate "Billing".
-
To try it, go to DistanceSubway.java, create a string contaning the API KEY. Instanciate a DistanceSubway object with two adresses (or coordinates) and the key.
-
Using calculateDistanceAdress method, get the distance in seconds between those two adresses. Without the key, you wouldn’t be able to use this class.
-
Go back to the cloud google website, and verify that the API request was successful. (Be aware, you only have 300$ of free credits).
-
For ideas about your next iterations, you can open idea.adoc. In this document, you will find all the ideas that we thought were interesting to add to the project but we didn’t have time to implement them.
Your time to play !