Cyclos web services and WEB-RPC

import org.cyclos.server.utils.HttpServiceFactory;
import org.cyclos.server.utils.HttpServiceInvocationData;

/**
 * This class will provide the Cyclos server configuration for the web service
 * samples
 */
public class Cyclos {

    private static final String ROOT_URL = "http://localhost:8888/england";

    private static HttpServiceFactory factory;

    static {
        factory = new HttpServiceFactory();
        factory.setRootUrl(ROOT_URL);
        factory.setInvocationData(HttpServiceInvocationData.stateless("admin", "1234"));
    }

    public static HttpServiceFactory getServiceFactory() {
        return factory;
    }

    public static HttpServiceFactory getServiceFactory(
        HttpServiceInvocationData invocationData) {
        var factory = new HttpServiceFactory();
        factory.setRootUrl(ROOT_URL);
        factory.setInvocationData(invocationData);
        return factory;
    }

}

import org.cyclos.model.users.users.UserQuery;
import org.cyclos.model.users.users.UserVO;
import org.cyclos.services.users.UserService;

/**
 * Provides a sample on searching for users
 */
public class SearchUsers {

    public static void main(String[] args) throws Exception {
        var userService = Cyclos.getServiceFactory().getProxy(UserService.class);

        // Search for the top 5 users by keywords
        var query = new UserQuery();
        query.setKeywords("consumer");
        query.setIgnoreProfileFieldsInList(true);
        query.setPageSize(5);
        var users = userService.search(query);

        System.out.printf("Found a total of %d users\n", users.getTotalCount());
        for (UserVO user : users) {
            System.out.printf("* %s\n", user.getDisplay());
        }
    }

}

import org.cyclos.model.marketplace.advertisements.BasicAdQuery;
import org.cyclos.model.marketplace.advertisements.BasicAdVO;
import org.cyclos.services.marketplace.AdService;

/**
 * Provides a sample on searching for advertisements
 */
public class SearchAds {

    public static void main(String[] args) throws Exception {
        var adService = Cyclos.getServiceFactory().getProxy(AdService.class);
        var query = new BasicAdQuery();
        query.setKeywords("Gear");
        query.setHasImages(true);
        var ads = adService.search(query);
        System.out.printf("Found a total of %d advertisements\n", ads.getTotalCount());
        for (BasicAdVO ad : ads) {
            System.out.printf("%s\nBy: %s\n%s\n-------\n",
                ad.getName(), ad.getOwner().getDisplay(),
                ad.getDescription());
        }
    }

}

import java.util.ArrayList;
import java.util.Arrays;

import org.cyclos.model.system.fields.CustomFieldDetailedVO;
import org.cyclos.model.system.fields.CustomFieldPossibleValueVO;
import org.cyclos.model.users.addresses.UserAddressDTO;
import org.cyclos.model.users.fields.UserCustomFieldValueDTO;
import org.cyclos.model.users.groups.BasicGroupVO;
import org.cyclos.model.users.groups.GroupVO;
import org.cyclos.model.users.phones.LandLinePhoneDTO;
import org.cyclos.model.users.phones.MobilePhoneDTO;
import org.cyclos.model.users.users.PasswordRegistrationDTO;
import org.cyclos.model.users.users.PasswordRegistrationData;
import org.cyclos.model.users.users.UserDataParams;
import org.cyclos.model.users.users.UserRegistrationDTO;
import org.cyclos.model.users.users.UserRegistrationData;
import org.cyclos.model.users.users.UserSearchContext;
import org.cyclos.services.users.UserService;
import org.cyclos.utils.CustomFieldHelper;

/**
 * Provides a sample on registering a user with all custom fields, addresses
 * and phones
 */
public class RegisterUser {

    public static void main(String[] args) {
        // Get the services
        var userService = Cyclos.getServiceFactory().getProxy(UserService.class);

        // The available groups for new users are obtained in the search data
        var searchData = userService.getSearchData(UserSearchContext.MENU, null);
        var possibleGroups = searchData.getInitialGroups();

        // Find the consumers group
        GroupVO group = null;
        for (BasicGroupVO current : possibleGroups) {
            if (current instanceof GroupVO && current.getName().equals("Consumers")) {
                group = (GroupVO) current;
                break;
            }
        }

        // Get data for a new user
        var params = new UserDataParams();
        params.setGroup(group);
        var data = (UserRegistrationData) userService.getDataForNew(params);

        // Basic fields
        var user = (UserRegistrationDTO) data.getDto();

        user.setPasswords(new ArrayList<PasswordRegistrationDTO>());
        var passwords = data.getPasswordsData();

        for (PasswordRegistrationData passData : passwords) {
            var passDTO = new PasswordRegistrationDTO();
            passDTO.setType(passData.getType());
            passDTO.setValue("1234");
            passDTO.setConfirmationValue("1234");
            passDTO.setAssign(true);
            passDTO.setForceChange(true);
            user.getPasswords().add(passDTO);
        }
        user.setGroup(group);
        user.setName("John Smith");
        user.setUsername("johnsmith");
        user.setEmail("john.smith@mail.com");
        user.setSkipActivationEmail(true);
        // Custom fields
        var customFields =
            CustomFieldHelper.getCustomFields(data.getProfileFieldActions());
        CustomFieldDetailedVO gender = null;
        CustomFieldDetailedVO idNumber = null;
        for (CustomFieldDetailedVO customField : customFields) {
            if (customField.getInternalName().equals("gender")) {
                gender = customField;
            }
            if (customField.getInternalName().equals("idNumber")) {
                idNumber = customField;
            }
        }
        user.setCustomValues(new ArrayList<UserCustomFieldValueDTO>());

        // Value for the gender custom field
        var genderValue = new UserCustomFieldValueDTO();
        genderValue.setField(gender);
        for (CustomFieldPossibleValueVO possibleValue : gender.getPossibleValues()) {
            if (possibleValue.getValue().equals("Male")) {
                // Found the value for 'Male'
                genderValue.setEnumeratedValue(possibleValue);
                break;
            }
        }
        user.getCustomValues().add(genderValue);

        // Value for id number custom field
        var idNumberValue = new UserCustomFieldValueDTO();
        idNumberValue.setField(idNumber);
        idNumberValue.setStringValue("123.456.789-10");
        user.getCustomValues().add(idNumberValue);

        // Address
        var address = new UserAddressDTO();
        address.setName("Home");
        address.setAddressLine1("John's Street, 500");
        address.setCity("John's City");
        address.setRegion("John's Region");
        address.setCountry("BR"); // Country is given in 2-letter ISO code
        user.setAddresses(Arrays.asList(address));

        // Landline phone
        var landLinePhone = new LandLinePhoneDTO();
        landLinePhone.setName("Home");
        landLinePhone.setRawNumber("+551133333333");
        user.setLandLinePhones(Arrays.asList(landLinePhone));

        // Mobile phone
        var mobilePhone = new MobilePhoneDTO();
        mobilePhone.setName("Mobile phone 1");
        mobilePhone.setRawNumber("+5511999999999");
        user.setMobilePhones(Arrays.asList(mobilePhone));

        // Effectively register the user
        var result = userService.register(user);
        var status = result.getStatus();
        switch (status) {
            case ACTIVE:
                System.out.println("The user is now active");
                break;
            case INACTIVE:
                System.out.println("The user is in an inactive group, "
                    + "and needs activation by administrators");
                break;
            case EMAIL_VALIDATION:
                System.out
                    .println("The user needs to validate the e-mail "
                        + "address in order to confirm the registration");
                break;
        }
    }

}

import org.cyclos.model.users.fields.UserCustomFieldValueDTO;
import org.cyclos.model.users.users.EditProfileData;
import org.cyclos.model.users.users.UserLocatorVO;
import org.cyclos.services.users.UserService;

public class EditUser {

    public static void main(String[] args) {
        // Get the services
        var userService = Cyclos.getServiceFactory().getProxy(UserService.class);

        // Locate the user by username, so we get the id
        var locate = new UserLocatorVO(UserLocatorVO.USERNAME, "some-user");
        var userVO = userService.locate(locate);

        // Get the profile data
        var data = (EditProfileData) userService.getData(userVO.getId());
        var user = data.getDto();
        user.setName("Some modified name");
        var customValues = user.getCustomValues();
        for (UserCustomFieldValueDTO fieldValue : customValues) {
            if (fieldValue.getField().getInternalName().equals("website")) {
                fieldValue.setStringValue("http://new.url.com");
            }
        }

        // Update the user
        userService.save(user);
        System.out.println("The user was updated.");
    }

}

import org.cyclos.model.access.LoggedOutException;
import org.cyclos.model.access.channels.BuiltInChannel;
import org.cyclos.model.banking.accounts.AccountWithStatusVO;
import org.cyclos.model.users.users.UserLocatorVO;
import org.cyclos.model.users.users.UserLoginDTO;
import org.cyclos.model.users.users.UserLoginResult;
import org.cyclos.server.utils.HttpServiceInvocationData;
import org.cyclos.services.access.LoginService;
import org.cyclos.services.banking.AccountService;

/**
 * Cyclos web service example: logs-in a user via web services.
 * This is useful when creating an alternative front-end for Cyclos.
 */
public class LoginUser {

    public static void main(String[] args) throws Exception {
        // This LoginService has the administrator credentials
        var loginService = Cyclos.getServiceFactory().getProxy(LoginService.class);

        // Another option is to use an access client to connect with the
        // server (for the admin)
        // To make it works you must:
        // 1- create an access client
        // 2- assign it to the admin (to obtain the activation code)
        // 3- activate it making a HTTP POST to the server using this url:
        // ROOT_URL/activate-access-client containing only the activation code
        // as the body
        // 4- put the token returned from the servlet as the parameter of the
        // HttpServiceInvocationData.accessClient(...) method
        // 5- comment the first line (that using user and password and
        // uncomment the following two sentences

        // HttpServiceInvocationData adminSessionInvocationData =
        // HttpServiceInvocationData
        // .accessClient("put_the_token_here");
        // LoginService loginService = Cyclos.getServiceFactory(
        // adminSessionInvocationData).getProxy(LoginService.class);

        var remoteAddress = "192.168.1.200";

        // Set the login parameters
        var params = new UserLoginDTO();
        params.setUser(new UserLocatorVO(UserLocatorVO.USERNAME, "some-user"));
        params.setPassword("1234");
        params.setRemoteAddress(remoteAddress);
        params.setChannel(BuiltInChannel.MAIN.getInternalName());

        // Login the user
        UserLoginResult result = loginService.loginUser(params);
        var userAuth = result.getUser();
        var sessionToken = result.getSessionToken();
        System.out.println("Logged-in '" + userAuth.getUser().getDisplay()
            + "' with session token = " + sessionToken);

        // Do something as user. As the session token is only valid per ip
        // address, we need to pass-in the client ip address again
        var sessionInvocationData =
            HttpServiceInvocationData.stateful(sessionToken, remoteAddress);
        // The services acquired by the following factory will carry on the
        // user session data
        var userFactory = Cyclos.getServiceFactory(sessionInvocationData);
        var accountService = userFactory.getProxy(AccountService.class);
        var accounts =
            accountService.getAccountsSummary(userAuth.getUser(), null);
        for (AccountWithStatusVO account : accounts) {
            System.out.println(account.getType()
                + ", balance: " + account.getStatus().getBalance());
        }

        // Logout. There are 2 possibilities:

        // - Logout as administrator:
        loginService.logoutUser(sessionToken);

        // - OR logout as own user:
        try {
            userFactory.getProxy(LoginService.class).logout();
        } catch (LoggedOutException e) {
            // already logged out
        }
    }

}

import java.math.BigDecimal;

import org.cyclos.model.banking.accounts.AccountHistoryEntryVO;
import org.cyclos.model.banking.accounts.AccountHistoryQuery;
import org.cyclos.model.banking.accounts.AccountWithStatusVO;
import org.cyclos.model.banking.accounttypes.AccountTypeNature;
import org.cyclos.model.users.users.UserLocatorVO;
import org.cyclos.model.users.users.UserVO;
import org.cyclos.services.banking.AccountService;

/**
 * Provides a sample on getting the account information for a given user.
 */
public class GetAccountInformation {

    public static void main(String[] args) throws Exception {
        var accountService =
            Cyclos.getServiceFactory().getProxy(AccountService.class);

        // Get the accounts summary
        var user = new UserLocatorVO(UserLocatorVO.USERNAME, "some-user");
        var accounts = accountService.getAccountsSummary(user, null);

        // For each account, we'll show the balances
        for (AccountWithStatusVO account : accounts) {
            var status = account.getStatus();
            if (status != null) {
                var balance = status.getBalance();
                System.out.printf("%s has balance of %.2f %s\n",
                    account.getType().getName(),
                    balance,
                    account.getCurrency());
            }

            // Also, search for the last 5 payments on each account
            var query = new AccountHistoryQuery();
            query.setAccount(account);
            query.setPageSize(5);

            var entries = accountService.searchAccountHistory(query);
            for (AccountHistoryEntryVO entry : entries) {
                var relatedAccount = entry.getRelatedAccount();
                var relatedType = relatedAccount.getType();
                var relatedNature = relatedType.getNature();
                // The from or to...
                String fromOrTo;
                if (relatedNature == AccountTypeNature.SYSTEM) {
                    // ... might be the account type name if a system account
                    fromOrTo = relatedType.getName();
                } else {
                    // ... or just the user display
                    var relatedUser = (UserVO) relatedAccount.getOwner();
                    fromOrTo = relatedUser.getDisplay();
                }
                // Display the amount, which can be negative or positive
                var amount = entry.getAmount();
                var debit = amount.compareTo(BigDecimal.ZERO) < 0;

                System.out.printf("Date: %s\n", entry.getDate());
                System.out.printf("%s: %s\n", debit ? "To" : "From", fromOrTo);
                System.out.printf("Amount: %.2f\n", amount);
                System.out.println();
            }
            System.out.println("**********");
        }
    }

}

import java.math.BigDecimal;

import org.cyclos.model.EntityNotFoundException;
import org.cyclos.model.banking.InsufficientBalanceException;
import org.cyclos.model.banking.MaxAmountPerDayExceededException;
import org.cyclos.model.banking.MaxAmountPerMonthExceededException;
import org.cyclos.model.banking.MaxAmountPerWeekExceededException;
import org.cyclos.model.banking.MaxAmountPerYearExceededException;
import org.cyclos.model.banking.MaxPaymentAmountExceededException;
import org.cyclos.model.banking.MaxPaymentsPerDayExceededException;
import org.cyclos.model.banking.MaxPaymentsPerMonthExceededException;
import org.cyclos.model.banking.MaxPaymentsPerWeekExceededException;
import org.cyclos.model.banking.MinTimeBetweenPaymentsException;
import org.cyclos.model.banking.accounts.InternalAccountOwner;
import org.cyclos.model.banking.accounts.SystemAccountOwner;
import org.cyclos.model.banking.transactions.PerformPaymentDTO;
import org.cyclos.model.banking.transactions.PerformPaymentData;
import org.cyclos.model.banking.transactions.TransactionAuthorizationStatus;
import org.cyclos.model.users.users.UserLocatorVO;
import org.cyclos.services.banking.PaymentService;
import org.cyclos.services.banking.TransactionService;
import org.cyclos.utils.CollectionHelper;

/**
 * Provides a sample on performing a payment between a user and a system
 * account
 */
public class PerformPayment {

    public static void main(String[] args) {
        // Get the services
        var factory = Cyclos.getServiceFactory();
        var transactionService = factory.getProxy(TransactionService.class);
        var paymentService = factory.getProxy(PaymentService.class);

        // The payer and payee
        InternalAccountOwner payer = new UserLocatorVO(UserLocatorVO.USERNAME, "some-user");
        InternalAccountOwner payee = SystemAccountOwner.instance();

        // Get data regarding the payment
        PerformPaymentData data;
        try {
            data = transactionService.getPaymentData(payer, payee, null);
        } catch (EntityNotFoundException e) {
            System.out.println("Some of the users were not found");
            return;
        }

        // Get the first available payment type
        var types = data.getPaymentTypes();
        var paymentType = CollectionHelper.first(types);
        if (paymentType == null) {
            System.out.println("There is no possible payment type");
        }

        // The payment amount
        var amount = new BigDecimal(10.5);

        // Perform the payment itself
        var payment = new PerformPaymentDTO();
        payment.setType(paymentType);
        payment.setOwner(data.getFrom());
        payment.setSubject(data.getTo());
        payment.setAmount(amount);

        try {
            var result = paymentService.perform(payment);
            // Check whether the payment is pending authorization
            var auth = result.getAuthorizationStatus();
            if (auth == TransactionAuthorizationStatus.PENDING_AUTHORIZATION) {
                System.out.println("The payment is pending authorization");
            } else {
                System.out.println("The payment has been processed");
            }
        } catch (InsufficientBalanceException e) {
            System.out.println("Insufficient balance");
        } catch (MaxPaymentsPerDayExceededException e) {
            System.out.println("Maximum daily amount of transfers "
                + e.getMaxPayments() + " has been reached");
        } catch (MaxPaymentsPerWeekExceededException e) {
            System.out.println("Maximum weekly amount of transfers "
                + e.getMaxPayments() + " has been reached");
        } catch (MaxPaymentsPerMonthExceededException e) {
            System.out.println("Maximum monthly amount of transfers "
                + e.getMaxPayments() + " has been reached");
        } catch (MinTimeBetweenPaymentsException e) {
            System.out.println("A minimum period of time should be awaited to make "
                + "a payment of this type");
        } catch (MaxAmountPerDayExceededException e) {
            System.out.println("Maximum daily amount of "
                + e.getMaxAmount() + " has been reached");
        } catch (MaxAmountPerWeekExceededException e) {
            System.out.println("Maximum weekly amount of "
                + e.getMaxAmount() + " has been reached");
        } catch (MaxAmountPerMonthExceededException e) {
            System.out.println("Maximum monthly amount of "
                + e.getMaxAmount() + " has been reached");
        } catch (MaxAmountPerYearExceededException e) {
            System.out.println("Maximum yearly amount of "
                + e.getMaxAmount() + " has been reached");
        } catch (MaxPaymentAmountExceededException e) {
            System.out.println("Maximum payment amount of "
                + e.getMaxAmount() + " has been reached");
        } catch (Exception e) {
            System.out.println("The payment couldn't be performed");
        }
    }

}

<?php

function load($c) {
    if (strpos($c, "Cyclos\\") >= 0) {
        include str_replace("\\", "/", $c) . ".php";
    }
}

spl_autoload_register('load');

Cyclos\Configuration::setRootUrl("http://localhost:8888/england");
Cyclos\Configuration::setAuthentication("admin", "1234");

?>

<?php

require_once 'configureCyclos.php';

$userService = new Cyclos\UserService();
$query = new stdclass();
$query->keywords = 'Consumer*';
$query->pageSize = 5;
$query->ignoreProfileFieldsInList = true;
$page = $userService->search($query);

echo("Found a total of $page->totalCount users\n");

if (!empty($page->pageItems)) {
	foreach ($page->pageItems as $user) {
		echo("* $user->display\n");
	}
}

?>

<?php

require_once 'configureCyclos.php';

$adService = new Cyclos\AdService();
$query = new stdclass();
$query->keywords = 'Computer*';
$query->pageSize = 10;
$query->orderBy = 'PRICE_LOWEST';
$page = $adService->search($query);

echo("Found a total of $page->totalCount advertisements\n");

if (!empty($page->pageItems)) {
	foreach ($page->pageItems as $ad) {
		echo("* $ad->name\n");
	}
}

?>

<?php

// Configure Cyclos and obtain an instance of LoginService
require_once 'configureCyclos.php';
$loginService = new Cyclos\LoginService();

// Set the parameters
$params = new stdclass();
$params->user = array("principal" => $_POST['username']);
$params->password = $_POST['password'];
$params->remoteAddress = $_SERVER['REMOTE_ADDR'];

// Perform the login
try {
	$result = $loginService->loginUser($params);
} catch (Cyclos\ConnectionException $e) {
	echo("Cyclos server couldn't be contacted");
	die();
} catch (Cyclos\ServiceException $e) {
	switch ($e->errorCode) {
		case 'VALIDATION':
			echo("Missing username / password");
			break;
		case 'LOGIN':
			echo("Invalid username / password");
			break;
		case 'REMOTE_ADDRESS_BLOCKED':
			echo("Your access is blocked by exceeding invalid login attempts");
			break;
		default:
			echo("Error while performing login: {$e->errorCode}");
			break;
	}
	die();
}

// Redirect the user to Cyclos with the returned session token
header("Location: "
	. Cyclos\Configuration::getRootUrl()
	. "?sessionToken="
	. $result->sessionToken);

?>

<?php
require_once 'configureCyclos.php';

$transactionService = new Cyclos\TransactionService();
$paymentService = new Cyclos\PaymentService();

try {
    $data = $transactionService->getPaymentData('SYSTEM', array('username' => 'c1'), null);

    $parameters = new stdclass();
    $parameters->from = $data->from;
    $parameters->to = $data->to;
    $parameters->type = $data->paymentTypes[0];
    $parameters->amount = 5;
    $parameters->description = "Test from system to user";

    $paymentResult = $paymentService->perform($parameters);
    if (isset($paymentResult->authorizationStatus) && $paymentResult->authorizationStatus == 'PENDING_AUTHORIZATION') {
        echo("Not yet authorized\n");
    } else {
        echo("Payment done with id $paymentResult->id\n");
    }
} catch (Cyclos\ServiceException $e) {
    echo("Error while calling $e->service.$e->operation: $e->errorCode");
}

?>

<?php
require_once 'configureCyclos.php';

//Perform the payment from user c1 to c2
Cyclos\Configuration::setAuthentication("c1", "1234");

$transactionService = new Cyclos\TransactionService();
$paymentService = new Cyclos\PaymentService();

try {
    $data = $transactionService->getPaymentData(
        array('username' => 'c1'),
        array('username' => 'c2'),
        null);

    $parameters = new stdclass();
    $parameters->from = $data->from;
    $parameters->to = $data->to;
    $parameters->type = $data->paymentTypes[0];
    $parameters->amount = 5;
    $parameters->description = "Test payment to user";

    $paymentResult = $paymentService->perform($parameters);
    if (isset($paymentResult->authorizationStatus) && $paymentResult->authorizationStatus == 'PENDING_AUTHORIZATION') {
        echo("Not yet authorized\n");
    } else {
        echo("Payment done with id $paymentResult->id\n");
    }
} catch (Cyclos\ServiceException $e) {
    switch ($e->errorCode) {
        case "VALIDATION":
            echo("Some of the parameters are invalid\n");
            var_dump($e->error);
            break;
        case "INSUFFICIENT_BALANCE":
            echo("Insufficient balance to perform the payment\n");
            break;
        case "MAX_AMOUNT_PER_DAY_EXCEEDED":
            echo("Maximum amount exeeded today\n");
            break;
        default:
            echo("Error with code $e->errorCode while performing the payment\n");
            break;
    }
}

?>