001/*
002 * Copyright (c) 2012, the Last.fm Java Project and Committers
003 * All rights reserved.
004 *
005 * Redistribution and use of this software in source and binary forms, with or without modification, are
006 * permitted provided that the following conditions are met:
007 *
008 * - Redistributions of source code must retain the above
009 *   copyright notice, this list of conditions and the
010 *   following disclaimer.
011 *
012 * - Redistributions in binary form must reproduce the above
013 *   copyright notice, this list of conditions and the
014 *   following disclaimer in the documentation and/or other
015 *   materials provided with the distribution.
016 *
017 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED
018 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
019 * PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
020 * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
021 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
022 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR
023 * TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
024 * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
025 */
026
027package de.umass.lastfm;
028
029import java.util.ArrayList;
030import java.util.Collection;
031import java.util.List;
032
033import de.umass.xml.DomElement;
034
035/**
036 * Provides the binding for the "tasteometer.compare" method.
037 *
038 * @author Janni Kovacs
039 */
040public class Tasteometer {
041
042        private Tasteometer() {
043        }
044
045        /**
046         * Get a Tasteometer score from two inputs, along with a list of shared artists.
047         *
048         * @param type1 Type of the first input
049         * @param value1 First input value
050         * @param type2 Type of the second input
051         * @param value2 Second input value
052         * @param apiKey The Last.fm API key
053         * @return result of Tasteometer comparison
054         */
055        public static ComparisonResult compare(InputType type1, String value1, InputType type2, String value2, String apiKey) {
056                Result result = Caller.getInstance().call("tasteometer.compare", apiKey, "type1", type1.name().toLowerCase(), "type2",
057                                                type2.name().toLowerCase(), "value1", value1, "value2", value2);
058                if (!result.isSuccessful())
059                        return null;
060                DomElement element = result.getContentElement();
061                DomElement re = element.getChild("result");
062                float score = Float.parseFloat(re.getChildText("score"));
063                List<Artist> artists = new ArrayList<Artist>();
064                for (DomElement domElement : re.getChild("artists").getChildren("artist")) {
065                        artists.add(ResponseBuilder.buildItem(domElement, Artist.class));
066                }
067                return new ComparisonResult(score, artists);
068        }
069
070        /**
071         * Contains the result of a tasteometer comparison, i.e. the score (0.0-1.0) and a list of
072         * shared artists.
073         */
074        public static class ComparisonResult {
075
076                private float score;
077                private Collection<Artist> matches;
078
079                ComparisonResult(float score, Collection<Artist> matches) {
080                        this.score = score;
081                        this.matches = matches;
082                }
083
084                /**
085                 * Returns a list of artist matches, i.e. artists both partys listen to.
086                 *
087                 * @return artist matches
088                 */
089                public Collection<Artist> getMatches() {
090                        return matches;
091                }
092
093                /**
094                 * Returns the compatability score between 0.0 (no compatability) and 1.0 (highest compatability).
095                 *
096                 * @return the score
097                 */
098                public float getScore() {
099                        return score;
100                }
101        }
102
103        /**
104         * Specifies the type of the input for the {@linkplain Tasteometer#compare Tasteometer.compare} operation.
105         */
106        public enum InputType {
107                USER,
108                ARTISTS,
109                MYSPACE
110        }
111}