package com.ciclourbana.comu;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

@Target(ElementType.TYPE)               // es pot posar sobre classes/interfícies
@Retention(RetentionPolicy.RUNTIME)     // sobreviu fins a l'execució
public @interface Provisional {
    String fins() default "modul-4";    // atribut amb valor per defecte
}

@Provisional(fins = "modul-4")
public class EstacioRepositoriEnMemoria { /* ... */ }

Class<?> classe = EstacioRepositoriEnMemoria.class;
Provisional marca = classe.getAnnotation(Provisional.class);

if (marca != null) {
    System.out.println("Classe provisional fins a: " + marca.fins());
    // -> Classe provisional fins a: modul-4
}

package com.ciclourbana;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class CicloUrbanaApplication {

    public static void main(String[] args) {
        SpringApplication.run(CicloUrbanaApplication.class, args);
    }
}

@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@SpringBootConfiguration
@EnableAutoConfiguration
@ComponentScan(excludeFilters = {
        @Filter(type = FilterType.CUSTOM, classes = TypeExcludeFilter.class),
        @Filter(type = FilterType.CUSTOM, classes = AutoConfigurationExcludeFilter.class)
})
public @interface SpringBootApplication {
    // atributs: exclude, excludeName, scanBasePackages, proxyBeanMethods...
}

package com.ciclourbana;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.SpringBootConfiguration;
import org.springframework.boot.autoconfigure.EnableAutoConfiguration;
import org.springframework.context.annotation.ComponentScan;

@SpringBootConfiguration          // 1. aquesta classe és una classe de configuració
@EnableAutoConfiguration          // 2. activa l'autoconfiguració
@ComponentScan                    // 3. escaneja aquest paquet i els de sota
public class CicloUrbanaApplication {

    public static void main(String[] args) {
        SpringApplication.run(CicloUrbanaApplication.class, args);
    }
}

// Escanejar un paquet addicional fora de l'arbre de com.ciclourbana
@SpringBootApplication(scanBasePackages = {"com.ciclourbana", "com.ribalta.pagaments"})
public class CicloUrbanaApplication { }

// Excloure una autoconfiguració concreta (ho veurem a 02-06)
@SpringBootApplication(exclude = DataSourceAutoConfiguration.class)
public class CicloUrbanaApplication { }

DataAccessException
├── DataIntegrityViolationException      (violació de restricció, clau duplicada)
├── DuplicateKeyException
├── EmptyResultDataAccessException       (s'esperava una fila i no n'hi va haver cap)
├── OptimisticLockingFailureException
└── CannotAcquireLockException           (temps d'espera de bloqueig exhaurit)

// A EstacioService, al mòdul 4. Avui encara no s'aplica.
try {
    return estacioRepositori.desar(nova);
} catch (DataIntegrityViolationException e) {
    // Val igual si a sota hi ha JDBC, JPA o MongoDB
    throw new EstacioDuplicadaException(nova.nom(), e);
}

package com.ciclourbana.comu;

import com.fasterxml.jackson.databind.ObjectMapper;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.client.RestClient;

import java.time.Clock;
import java.time.ZoneId;

/**
 * Beans d'infraestructura de CicloUrbana que provenen de llibreries
 * externes i que, per tant, no es poden anotar amb @Component.
 */
@Configuration
public class ConfiguracioComuna {

    /**
     * Rellotge centralitzat. Injectar un Clock en comptes de cridar
     * LocalDateTime.now() permet fixar l'hora a les proves (mòdul 6).
     * El nom del bean és el del mètode: "rellotgeRibalta".
     */
    @Bean
    public Clock rellotgeRibalta() {
        return Clock.system(ZoneId.of("Europe/Madrid"));
    }

    /**
     * Client HTTP per cridar el servei municipal de trànsit.
     * L'utilitzarem de debò al mòdul 7; aquí serveix d'exemple
     * de bean construït a mà amb un builder.
     */
    @Bean
    public RestClient clientTransitRibalta() {
        return RestClient.builder()
                .baseUrl("https://transit.ribalta.example/api")
                .build();
    }
}

@Configuration
public class ConfiguracioComuna {

    @Bean
    public Clock rellotgeRibalta() {
        return Clock.system(ZoneId.of("Europe/Madrid"));
    }

    @Bean
    public RegistreAuditoria registreAuditoria() {
        return new RegistreAuditoria(rellotgeRibalta());   // crea un segon Clock?
    }
}

@Configuration(proxyBeanMethods = false)   // mode "lite": arrencada una mica més ràpida
public class ConfiguracioComuna { }

@ComponentScan(
        basePackages = {"com.ciclourbana", "com.ribalta.compartit"},
        // alternativa amb seguretat de tipus: si mous la classe, el paquet s'ajusta sol
        basePackageClasses = {CicloUrbanaApplication.class},
        includeFilters = @ComponentScan.Filter(
                type = FilterType.ANNOTATION,
                classes = ServeiXarxa.class),
        excludeFilters = @ComponentScan.Filter(
                type = FilterType.REGEX,
                pattern = "com\\.ciclourbana\\..*\\.llegat\\..*")
)

@SpringBootApplication
@ComponentScan(excludeFilters = @ComponentScan.Filter(
        type = FilterType.REGEX,
        pattern = "com\\.ciclourbana\\.simulacio\\..*"))
public class CicloUrbanaApplication { }

package com.ciclourbana.comu;

import org.springframework.core.annotation.AliasFor;
import org.springframework.stereotype.Service;

import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

/**
 * Estereotip propi: marca un servei del nucli operatiu de la xarxa
 * de Ribalta. És un @Service a tots els efectes, més una etiqueta
 * semàntica que permet localitzar-los i tractar-los en bloc.
 */
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Documented
@Service                                    // <-- la meta-anotació clau
public @interface ServeiXarxa {

    /** Àrea funcional a la qual pertany el servei. */
    String area() default "general";

    /** Permet fixar el nom del bean, igual que @Service. */
    @AliasFor(annotation = Service.class, attribute = "value")
    String value() default "";
}

@ServeiXarxa(area = "estacions")
public class EstacioService { /* ... */ }

Map<String, Object> serveisNucli =
        context.getBeansWithAnnotation(ServeiXarxa.class);
// {estacioService=..., lloguerService=...}

package com.ciclourbana.estacions;

import java.util.List;
import java.util.Optional;

/**
 * Contracte d'accés a dades d'estacions. La interfície permet
 * substituir la implementació en memòria per la de JPA (mòdul 4)
 * sense tocar EstacioService.
 */
public interface EstacioRepositori {

    List<Estacio> cercarTotes();

    Optional<Estacio> cercarPerId(Long id);

    Estacio desar(Estacio estacio);

    long comptar();
}

package com.ciclourbana.estacions;

import org.springframework.stereotype.Repository;

import java.util.List;
import java.util.Map;
import java.util.Optional;
import java.util.concurrent.ConcurrentHashMap;
import java.util.concurrent.atomic.AtomicLong;

/**
 * Implementació provisional en memòria del repositori d'estacions.
 * Se substituirà per Spring Data JPA al mòdul 4.
 *
 * Utilitza ConcurrentHashMap perquè el bean és singleton i diverses
 * peticions HTTP concurrents el comparteixen (es raona a fons a la lliçó 02-03).
 */
@Repository
public class EstacioRepositoriEnMemoria implements EstacioRepositori {

    private final Map<Long, Estacio> perId = new ConcurrentHashMap<>();
    private final AtomicLong seguentId = new AtomicLong(0);

    @Override
    public List<Estacio> cercarTotes() {
        return List.copyOf(perId.values());
    }

    @Override
    public Optional<Estacio> cercarPerId(Long id) {
        return Optional.ofNullable(perId.get(id));
    }

    @Override
    public Estacio desar(Estacio estacio) {
        Long id = (estacio.id() != null)
                ? estacio.id()
                : seguentId.incrementAndGet();

        // El record és immutable: si assignem id, en construïm un de nou
        Estacio aDesar = (estacio.id() != null) ? estacio : new Estacio(
                id, estacio.nom(), estacio.adreca(),
                estacio.capacitat(), estacio.latitud(), estacio.longitud());

        perId.put(id, aDesar);
        seguentId.updateAndGet(actual -> Math.max(actual, id));
        return aDesar;
    }

    @Override
    public long comptar() {
        return perId.size();
    }
}

package com.ciclourbana.estacions;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.stereotype.Service;

import java.util.Comparator;
import java.util.List;
import java.util.Optional;

/**
 * Lògica de negoci de les estacions de la xarxa de Ribalta.
 * No coneix HTTP (això és del controlador) ni com s'emmagatzemen
 * les dades (això és del repositori).
 */
@Service
public class EstacioService {

    private static final Logger log = LoggerFactory.getLogger(EstacioService.class);

    private final EstacioRepositori estacioRepositori;

    // Injecció per constructor: s'explica a fons a la lliçó 02-02
    public EstacioService(EstacioRepositori estacioRepositori) {
        this.estacioRepositori = estacioRepositori;
    }

    public List<Estacio> llistarTotes() {
        return estacioRepositori.cercarTotes().stream()
                .sorted(Comparator.comparing(Estacio::nom))
                .toList();
    }

    public Optional<Estacio> cercarPerId(Long id) {
        return estacioRepositori.cercarPerId(id);
    }

    public Estacio registrar(Estacio estacio) {
        // Regla de negoci de Ribalta: cap estació amb menys de 8 ancoratges
        if (estacio.capacitat() < 8) {
            throw new IllegalArgumentException(
                    "Una estació de Ribalta requereix com a mínim 8 ancoratges; rebuts: "
                            + estacio.capacitat());
        }
        Estacio desada = estacioRepositori.desar(estacio);
        log.info("Estació registrada: {} ({} ancoratges)",
                desada.nom(), desada.capacitat());
        return desada;
    }

    public int capacitatTotalXarxa() {
        return estacioRepositori.cercarTotes().stream()
                .mapToInt(Estacio::capacitat)
                .sum();
    }

    public long comptar() {
        return estacioRepositori.comptar();
    }
}

package com.ciclourbana.estacions;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import java.util.List;

@RestController
@RequestMapping("/api/v1/estacions")
public class EstacioController {

    private final EstacioService estacioService;

    public EstacioController(EstacioService estacioService) {
        this.estacioService = estacioService;
    }

    @GetMapping
    public List<Estacio> llistarEstacions() {
        return estacioService.llistarTotes();
    }
}

package com.ciclourbana.estacions;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.boot.CommandLineRunner;
import org.springframework.core.annotation.Order;
import org.springframework.stereotype.Component;

@Component
@Order(1)
public class CarregadorEstacionsDemo implements CommandLineRunner {

    private static final Logger log = LoggerFactory.getLogger(CarregadorEstacionsDemo.class);

    private final EstacioService estacioService;

    public CarregadorEstacionsDemo(EstacioService estacioService) {
        this.estacioService = estacioService;
    }

    @Override
    public void run(String... args) {
        log.info("Carregant estacions de demostració de Ribalta...");

        estacioService.registrar(new Estacio(1L, "Plaça Major",
                "Plaça Major, 1", 24, 40.4168, -3.7038));
        estacioService.registrar(new Estacio(2L, "Estació Nord",
                "Avinguda Estació 3", 30, 40.4290, -3.7020));
        estacioService.registrar(new Estacio(3L, "Parc del Riu",
                "Passeig Fluvial 12", 18, 40.4105, -3.6950));
        estacioService.registrar(new Estacio(4L, "Universitat",
                "Campus Sud, accés B", 36, 40.4402, -3.7255));

        log.info("Carregades {} estacions, {} ancoratges en total",
                estacioService.comptar(), estacioService.capacitatTotalXarxa());
    }
}

./mvnw spring-boot:run

curl -s http://localhost:8080/api/v1/estacions | head -5

package com.ciclourbana;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.SpringBootConfiguration;
import org.springframework.boot.autoconfigure.EnableAutoConfiguration;
import org.springframework.context.annotation.ComponentScan;

@SpringBootConfiguration    // = @Configuration especialitzat, àncora de les proves
@EnableAutoConfiguration    // activa l'autoconfiguració (lliçó 02-06)
@ComponentScan              // escaneja com.ciclourbana i subpaquets
public class CicloUrbanaApplication {

    public static void main(String[] args) {
        SpringApplication.run(CicloUrbanaApplication.class, args);
    }
}

package com.ciclourbana.comu;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.boot.CommandLineRunner;
import org.springframework.context.ApplicationContext;
import org.springframework.core.annotation.Order;
import org.springframework.stereotype.Component;

@Component
@Order(100)   // després del carregador d'estacions, que és @Order(1)
public class VerificadorBeans implements CommandLineRunner {

    private static final Logger log = LoggerFactory.getLogger(VerificadorBeans.class);

    private final ApplicationContext context;

    public VerificadorBeans(ApplicationContext context) {
        this.context = context;
    }

    @Override
    public void run(String... args) {
        for (String nom : new String[]{
                "estacioService", "estacioRepositoriEnMemoria", "estacioController"}) {
            log.info("Bean '{}' present: {} -> {}",
                    nom,
                    context.containsBean(nom),
                    context.containsBean(nom)
                            ? context.getBean(nom).getClass().getSimpleName()
                            : "N/D");
        }
    }
}

Bean 'estacioService' present: true -> EstacioService
Bean 'estacioRepositoriEnMemoria' present: true -> EstacioRepositoriEnMemoria
Bean 'estacioController' present: true -> EstacioController

package com.ciclourbana.comu;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import java.time.Clock;
import java.time.ZoneId;
import java.util.Random;

@Configuration(proxyBeanMethods = false)   // cap mètode @Bean en crida un altre
public class ConfiguracioComuna {

    /** Rellotge de la xarxa. Injectar-lo permet congelar el temps a les proves. */
    @Bean
    public Clock rellotgeRibalta() {
        return Clock.system(ZoneId.of("Europe/Madrid"));
    }

    /** Llavor fixa: les simulacions de demanda són reproduïbles. */
    @Bean
    public Random aleatoriSimulacio() {
        return new Random(42L);
    }
}

package com.ciclourbana.comu;

import org.springframework.stereotype.Component;

import java.time.Clock;
import java.time.LocalDateTime;

@Component
public class RellotgeXarxa {

    private final Clock rellotge;

    public RellotgeXarxa(Clock rellotge) {
        this.rellotge = rellotge;
    }

    public LocalDateTime instantActual() {
        return LocalDateTime.now(rellotge);
    }
}

package com.ciclourbana.comu;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.boot.CommandLineRunner;
import org.springframework.stereotype.Component;

@Component
public class AvisHoraArrencada implements CommandLineRunner {

    private static final Logger log = LoggerFactory.getLogger(AvisHoraArrencada.class);

    private final RellotgeXarxa rellotgeXarxa;

    public AvisHoraArrencada(RellotgeXarxa rellotgeXarxa) {
        this.rellotgeXarxa = rellotgeXarxa;
    }

    @Override
    public void run(String... args) {
        log.info("CicloUrbana arrenca a les {} (hora de Ribalta)",
                rellotgeXarxa.instantActual());
    }
}

package com.ciclourbana.comu;

import org.springframework.core.annotation.AliasFor;
import org.springframework.stereotype.Service;

import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Documented
@Service
public @interface ServeiXarxa {

    String area() default "general";

    @AliasFor(annotation = Service.class, attribute = "value")
    String value() default "";
}

// A EstacioService, substituint @Service:
@ServeiXarxa(area = "estacions")
public class EstacioService { /* ... */ }

package com.ciclourbana.comu;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.boot.CommandLineRunner;
import org.springframework.context.ApplicationContext;
import org.springframework.core.annotation.AnnotationUtils;
import org.springframework.core.annotation.Order;
import org.springframework.stereotype.Component;

import java.util.Map;

@Component
@Order(200)
public class InventariServeisXarxa implements CommandLineRunner {

    private static final Logger log = LoggerFactory.getLogger(InventariServeisXarxa.class);

    private final ApplicationContext context;

    public InventariServeisXarxa(ApplicationContext context) {
        this.context = context;
    }

    @Override
    public void run(String... args) {
        Map<String, Object> serveis = context.getBeansWithAnnotation(ServeiXarxa.class);

        log.info("Serveis del nucli de la xarxa: {}", serveis.size());
        serveis.forEach((nom, bean) -> {
            // findAnnotation travessa proxies i jerarquies; getAnnotation no sempre
            ServeiXarxa marca = AnnotationUtils.findAnnotation(
                    bean.getClass(), ServeiXarxa.class);
            log.info("  - {} (àrea: {})", nom,
                    marca != null ? marca.area() : "desconeguda");
        });
    }
}

Serveis del nucli de la xarxa: 1
  - estacioService (àrea: estacions)